Merge pull request #229 from mocks-server/release

Next release v3.2

Author: javierbrea

custom-wordlist.txt

@@ -15,6 +15,7 @@ cors
 CORS
 customizable
 dependant
+descendent
 Docusaurus
 ecmascript
 env
@@ -38,6 +39,7 @@ lifecycle
 localhost
 middleware
 middlewares
+mocksServer
 Namespaces
 namespaces
 Namespace
@@ -56,6 +58,7 @@ md
 redux
 reusability
 stringified
+subcollection
 subfolders
 submenu
 theirself
@@ -64,4 +67,4 @@ url
 uri
 uris
 www
-mocksServer
+

docs/api-mocks-server-api.md

@@ -23,7 +23,7 @@ const Core = require("@mocks-server/core");
 const AdminApi = require("@mocks-server/plugin-admin-api");
 const InquirerCli = require("@mocks-server/plugin-inquirer-cli");
 
-const mocksServer = new Core({
+const core = new Core({
   config: {
     readFile: false,
     readEnvironment: false,
@@ -34,8 +34,7 @@ const mocksServer = new Core({
   },
 });
 
-mocksServer
-  .init({
+core.init({
     server: {
       port: 3500
     },
@@ -44,7 +43,7 @@ mocksServer
     },
     log: "debug"
   })
-  .then(server.start);
+  .then(core.start);
 ```
 
 ## Core API
@@ -57,4 +56,4 @@ mocksServer
 
 ## Core instance API
 
-Please read the `mocksServer` API chapter to know all available methods and getters in the `mocksServer` instance that the `Core` class returns.
+Please read the [`core` API chapter](api-mocks-server-api.md) to know all available methods and getters in the `core` instance that the `Core` class returns.

docs/api-programmatic-usage.md

@@ -1,7 +1,7 @@
 ---
 id: api-routes-and-mocks
 title: Routes and Mocks
-description: mocksServer API
+description: Routes and Mocks API
 keywords:
   - mocks server
   - api

docs/api-routes-and-mocks.md

@@ -34,10 +34,10 @@ This static getter must return a JSON schema defining the specific properties re
 * You must only define those properties added by the route handler to the variant definition. Those that are common to all route variant types must not be defined. So, you shouldn't use `additionalProperties:false` at the root level of the schema. Otherwise, the properties that are common to all route variants would be considered invalid.
 * Mocks Server supports a special JSON schema keyword named `instanceof`. You can use it to indicate that a property must be an instance of a `function`, or a `RegExp` for example.
 
-#### `constructor(route, mocksServer)`
+#### `constructor(route, core)`
 
 * `route`: All route and route variants properties from the `route` definition _(`method`, `url`, `variantId`, and all other properties defined in the route variant object)_.
-* `mocksServer`: The [`mocksServer` instance](api-mocks-server-api.md).
+* `core`: The [`core` instance](api-mocks-server-api.md), but with some methods specifically scoped for each route variant, such as `core.logger` and `core.alerts`, which are namespaced using each route variant id. So, logs or alerts from each different route variant can be easily identified.
 
 #### `middleware(req, res, next)`
 
@@ -59,14 +59,15 @@ class CustomRoutesHandler {
     return "error";
   }
 
-  constructor(routeVariant, mocksServer) {
+  constructor(routeVariant, core) {
     this._error = routeVariant.error;
     this._variantId = routeVariant.variantId;
-    this._mocksServer = mocksServer;
+    this._core = core;
   }
 
   middleware(req, res, next) {
-    this._mocksServer.tracer.info(`Sending route variant "${this._variantId}"`);
+    // Next log automatically includes the route variant id
+    this._core.logger.info("Sending response");
     res.status(this._error.code);
     res.send({
       message: this._error.message
@@ -105,7 +106,7 @@ module.exports = {
 ```
 
 :::note
-You can also add Route Handlers programmatically using the [`mocksServer.addRoutesHandler` method](api-mocks-server-api.md) (useful to be used from [plugins](plugins-developing-plugins.md), for example)
+You can also add Route Handlers programmatically using the [`core.addRoutesHandler` method](api-mocks-server-api.md) (useful to be used from [plugins](plugins-developing-plugins.md), for example)
 :::
 
 And now, you can use the custom handler when defining route variants:

docs/api-routes-handler.md

@@ -17,7 +17,7 @@ keywords:
 
 This project provides a mock server that can __simulate and store multiple API responses for each different route__. It can be added as a dependency of your project, and started simply running an NPM command.
 
-Providing an interactive command line user interface and a REST API for __changing the responses of the API while it is running, it is easy to use both for development and testing__.
+Providing an interactive command line user interface and a REST API for __changing the responses of the mocked API while it is running, it is easy to use both for development and testing__.
 
 ### Main features
 

docs/get-started-intro.md

@@ -39,11 +39,11 @@ The format for defining a route is to declare an object containing:
           * __`headers`__ _(Object)_: Object containing headers to set in the response.
           * __`status`__ _(Number)_: Status code to send.
           * __`body`__ _(Object)_: Object to send as body in the response.
-        * `middleware(req, res, next, mocksServer)`
+        * `middleware(req, res, next, core)`
           * __`req`__ Express middleware `req` object.
           * __`res`__ Express middleware `res` methods.
           * __`next`__ Express middleware `next` method.
-          * __`mocksServer`__ Mocks Server instance methods. Using this you could change the settings of the server itself from a request. [Read the API docs for further info](api-mocks-server-api.md) about available methods.
+          * __`core`__ Mocks Server core instance methods. Using this you could change the settings of the server itself from a request, for example. [Read the API docs for further info](api-mocks-server-api.md) about all available methods.
     * _`handler:"proxy"`_ [Proxy handler](plugins-proxy.md) provided by `@mocks-server/plugin-proxy`, included in the "main" distribution. The variant can contain next extra properties:
       * __`host`__ _(String|Function)_: The proxy host. Equivalent to the [`express-http-proxy` `host` option](https://github.com/villadora/express-http-proxy#host), so it can also be a function.
       * __`options`__ _(Object)_: Object containing any of the [options supported by the `express-http-proxy` package](https://github.com/villadora/express-http-proxy#options). Some of them are:

docs/get-started-routes.md

@@ -15,7 +15,7 @@ keywords:
 
 ## Preface
 
-Mocks Server v2.x introduced the concept of ["route variants"](get-started-intro.md), and made more restrictive the way for organizing mocks and routes files. It also introduced other improvements, as the possibility of [using express middlewares](guides-using-middlewares.md), made simpler the [mocksServer API](api-mocks-server-api.md), etc.
+Mocks Server v2.x introduced the concept of ["route variants"](get-started-intro.md), and made more restrictive the way for organizing mocks and routes files. It also introduced other improvements, as the possibility of [using express middlewares](guides-using-middlewares.md), made simpler the [core API](api-mocks-server-api.md), etc.
 
 All of these changes made very difficult to handle old v1 `behaviors` and `fixtures` together with the new format of `routes`, so, in order to maintain backward compatibility, Mocks Server v2 can handle two folders at a time, one containing v1.x `fixtures` and `behaviors`, and another one containing v2.x [`mocks`](get-started-mocks.md) and [`routes`](get-started-routes.md).
 

docs/guides-migrating-from-v1.md

@@ -130,7 +130,11 @@ In order to make compatible your plugins with the v3 version, you have to:
 
 * Add an `id` property to them (an static property in the case of Class plugins). This allows the core to create an appropriate namespace for the plugins and pass to them the correspondent `config` and `alerts` objects.
 * Change the Core API deprecated methods for creating and reading settings if you were using them by the new ones. Read the [configuration API section bellow for further info](#configuration-api).
-* Change the arguments that they receive in the `constructor`, `register`, `init`, `start` and `stop` methods. Now they will receive a single argument as an object containing all needed methods and properties. Previously, the `core` API was received as first argument, and from now it is received as a `{ core }` property in the first argument. So a plugin that in V2 was defined as:
+* Change the arguments that they receive in the `constructor`, `register`, `init`, `start` and `stop` methods. Now they will receive:
+  * __3.1__: A single argument as an object containing all needed methods and properties Previously, the `core` API was received as first argument, and from now it is received as a `{ core }` property in the first argument.
+  * __>=3.2__: A Mocks Server [`core` instance](api-mocks-server-api.md), but with some methods specifically scoped for the plugin. The core API docs also give details about the methods that are modified when the core is passed to a plugin.
+
+So, a plugin that in v2 was defined as:
 
 ```js
 class Plugin {
@@ -160,43 +164,54 @@ class Plugin {
 }
 ```
 
-Now it has to be defined as:
+In v3.1 had to be defined as in the next example, but you shouldn't use the `core` property, because it will be removed in the next major version. __Better use the `v3.2` example, which will be fully compatible with v4.__
 
 ```js
 class Plugin {
-  static get id() {
-    return "myPlugin";
-  }
+  static id = "myPlugin";
 
   constructor({ core, loadMocks, loadRoutes, alerts, config }) {
     // Do your stuff here
   }
+}
+```
+
+__And in any version equal or greater than v3.2 it has to be defined as:__
 
-  register({ core, loadMocks, loadRoutes, alerts, config }) {
+```js
+class Plugin {
+  static id = "myPlugin";
+
+  constructor({ onChangeMocks, onChangeAlerts, logger, loadMocks, loadRoutes, alerts, config }) {
+    // Here you receive all of the core API methods in one single argument
+    // The parameter is destructured only for example purpose
+  }
+
+  register(core) {
     // Do your stuff here
   }
 
-  init({ core, loadMocks, loadRoutes, alerts, config }) {
+  init(core) {
     // Do your stuff here
   }
 
-  start({ core, loadMocks, loadRoutes, alerts, config }) {
+  start(core) {
     // Do your stuff here
   }
 
-  stop({ core, loadMocks, loadRoutes, alerts, config }) {
+  stop(core) {
     // Do your stuff here
   }
 }
 ```
 
 :::note
-The old `addAlert` and `removeAlerts` methods can still be used in v3, but they are considered deprecated since v3.1.0 and will be removed in next major version. Any usage of these methods would produce an alert. Read the [updated documentation about creating plugins](plugins-developing-plugins.md) for further info about how to use them.
+The old `addAlert` and `removeAlerts` methods can still be used in v3, but they are considered deprecated since v3.1.0 and will be removed in next major version. The `core` property added in v3.1 can be still used in any v3.x version, but it will be also removed in v4. Any usage of these methods would produce an alert. Read the [updated documentation about creating plugins](plugins-developing-plugins.md) for further info about how to use them.
 :::
 
 ## Configuration API
 
-As a result of the [programmatic API changes](#programmatic-api), old methods for creating or reading settings are not available any more, such as `mocksServer.addSetting`, `mocksServer.settings.get`, `mocksServer.settings.set` or `mocksServer.lowLevelConfig`. Now you can create, read, or listen to configuration changes using the `mocksServer.config` object, or using the `config` object received in plugins, which is already namespaced with each plugin name. Here you have a brief example of how you can migrate from one system to another. For further information, you should read the [updated documentation about creating plugins](plugins-developing-plugins.md).
+As a result of the [programmatic API changes](#programmatic-api), old methods for creating or reading settings are not available any more, such as `core.addSetting`, `core.settings.get`, `core.settings.set` or `core.lowLevelConfig`. Now you can create, read, or listen to configuration changes using the `core.config` object, or using the `config` object received in plugins, which is already namespaced with each plugin name. Here you have a brief example of how you can migrate from one system to another. For further information, you should read the [updated documentation about creating plugins](plugins-developing-plugins.md).
 
 If you were creating or reading settings like this in v2:
 
@@ -225,29 +240,27 @@ class Plugin {
 }
 ```
 
-Now you have to do it like this in v3:
+Now you have to do it like this in >=3.2:
 
 ```js
 class Plugin {
-  static get id() {
-     return "myPlugin";
-  }
+  static id = "myPlugin";
 
-  constructor({ core, config }) {
+  constructor(core) {
     this._core = core;
-    this._myOption = config.addOption({
+    this._myOption = core.config.addOption({
       name: "myOption",
       type: "string",
     });
   }
 
   start() {
-    this._core.tracer.info(`Current value of my option is ${this._myOption.value}`);
+    this._core.logger.info(`Current value of my option is ${this._myOption.value}`);
     this._myOption.onChange(this._onChangeMyOption.bind(this));
   }
 
   _onChangeMyOption(newValue) {
-    this._core.tracer.info(`My option changed to: ${newValue}`);
+    this._core.logger.info(`My option changed to: ${newValue}`);
   }
 }
 ```

docs/guides-migrating-from-v2.md

@@ -0,0 +1,67 @@
+---
+id: guides-migrating-from-v3
+title: Preparing for v4
+description: How to prepare migration from v3.x to v4.x
+keywords:
+  - mocks server
+  - tutorial
+  - migration
+  - version
+  - update
+  - legacy
+  - guide
+  - deprecated
+---
+
+:::warning
+If you are already using Mocks Server v2.x you should [migrate first from v2.x to v3.x](guides-migrating-from-v2.md), and then read this chapter to prepare migration to v4.x.
+:::
+
+## Preface
+
+Even when v4 release is still not published, we are deprecating some things in v3 that will be removed in v4. While v4 is not released, every change in v3.x will be completely backward compatible, but __users upgrading to next minor versions would probably receive alerts about usage of deprecated methods, etc__.
+
+So, every time you upgrade a minor version and receive a deprecation alert, you can come to this page and see how to adapt your code for the next major version, so you'll be able to prepare to it progressively and finally update to v4 without breaking changes.
+
+
+## Changes summary
+
+The main breaking changes in v4.x will be:
+
+* __Some core API methods will be removed__. Read [core API](#core-api) below for further info.
+* __Legacy alerts object will be removed__. Read [alerts](#alerts) for further info.
+* __Arguments received by the plugins__. Read [plugins](#plugins) below for further info.
+
+## Core API
+
+* __`core.tracer`__: The `tracer` object will be completely removed and using it from v3.2 produces an alert. You must use `core.logger` instead, which is already namespaced when passed to plugins and route middlewares. [Read the logger API docs](api-mocks-server-api.md#logger) for further info.
+
+## Alerts
+
+* The __`core.alerts`__ getter in the core when created programmatically was different to the `core.alerts` property received in the plugins from v3.2 due to backward compatibility reasons. In v4 it will return an `alerts` instance in the first case too. In the first case, it was returning a plain alerts collection. So, if you are using a programmatic root core, you should start using `core.alertsApi.customFlat` to get the same values, because that alias will be maintained in v4. Note that, in the case of plugins, you should continue using the `alerts` property, which will not change in v4.
+* The __`addAlert`__ and __`removeAlerts`__ methods that were being passed to plugins were deprecated in v3.1, and they will be removed in v4. Plugins were receiving an `alerts` property in the core to be used instead, which was also available in the root programmatic core using `core.alertsApi`. [Read the alerts API docs](api-mocks-server-api.md#alerts) for further info.
+
+
+## Plugins
+
+### Core property
+
+In version 3.1 a `core` property was added to the argument passed to the plugins. From `v3.2`, the whole core API was passed as first argument, but with some methods specifically scoped for the plugin. The `core` property was also maintained for backward compatibility but using it produced an alert. So, in v4 the `core` property will be definitively removed.
+
+V3 example:
+
+```js
+class Plugin {
+  constructor({ loadMocks, core, loadRoutes, addAlert, removeAlerts }) {
+    // core property was almost an alias containing again all of the rest of properties received
+  }
+}
+```
+V4 example:
+```js
+class Plugin {
+  constructor({ loadMocks, loadRoutes, addAlert, removeAlerts }) {
+    // core property is no longer received
+  }
+}
+```