mock-config-server 3.7.0 → 4.0.0

package/README.md

@@ -38,10 +38,12 @@ $ yarn add mock-config-server --dev
 Create a `mock-server.config.js` file with server configuration
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/user',
@@ -50,9 +52,9 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
 Start **🎉 Mock Config Server**
@@ -65,22 +67,23 @@ $ npx mock-config-server
 
 ## 🎭 Parameters for mock-server.config.(js|ts)
 
-- `rest?` Rest configs for mock requests
-  - `baseUrl?` `string` part of the url that will be substituted at the beginning of rest request url (default: `'/'`)
-  - `configs` `Array<RestRequestConfig>` configs for mock requests, [read](#configs)
-  - `interceptors?` `Interceptors` functions to change request or response parameters, [read](#interceptors)
-- `graphql?` GraphQL configs for mock requests
-  - `baseUrl?` `string` part of the url that will be substituted at the beginning of graphql request url (default: `'/'`)
-  - `configs` `Array<GraphQLRequestConfig>` configs for mock requests, [read](#configs)
-  - `interceptors?` `Interceptors` functions to change request or response parameters, [read](#interceptors)
+### Settings
+
+- `staticPath?` {StaticPath} entity for working with static files, [read](#static-path)
+- `interceptors?` {Interceptors} functions to change request or response parameters, [read](#interceptors)
+- `cors?` {Cors} CORS settings object (default: `CORS is turn off`), [read](#cors)
+- `port?` {number} server port (default: `31299`)
+- `baseUrl?` {string} part of the url that will be substituted at the beginning of the request url (default: `'/'`)
 - `database?` Database config for mock requests [read](#database)
-  - `data` `Object | string` initial data for database
-  - `routes?` `Object | string` map of custom routes for database
-- `staticPath?` `StaticPath` entity for working with static files, [read](#static-path)
-- `interceptors?` `Interceptors` functions to change request or response parameters, [read](#interceptors)
-- `cors?` `Cors` CORS settings object (default: `CORS is turn off`), [read](#cors)
-- `port?` `number` server port (default: `31299`)
-- `baseUrl?` `string` part of the url that will be substituted at the beginning of the request url (default: `'/'`)
+  - `data` {Object | string} initial data for database
+  - `routes?` {Object | string} map of custom routes for database
+
+### Components
+
+- `name` {string} name of component
+- `baseUrl?` {string} part of the url that will be substituted at the beginning of rest request url (default: `'/'`)
+- `configs` {Array<RestRequestConfig | GraphQLRequestConfig>} configs for mock requests, [read](#configs)
+  - `interceptors?` {Interceptors} functions to change request or response parameters, [read](#interceptors)
 
 ### Configs
 
@@ -104,10 +107,12 @@ Every route must be configured to handle response content in one of three ways:
 ##### Rest example
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/user',
@@ -129,9 +134,9 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+export default flatMockServerConfig;
 ```
 
 Now you can make a request with an additional header and get the desired result
@@ -167,10 +172,12 @@ Every route must be configured to handle response content in one of two ways: da
 ##### GraphQL example
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  graphql: {
-    baseUrl: '/graphql',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/graphql'
+  },
+  {
     configs: [
       {
         operationType: 'query',
@@ -192,9 +199,9 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+export default flatMockServerConfig;
 ```
 
 Now you can make a request with an additional header and get the desired result
@@ -236,13 +243,13 @@ Allowed `checkModes`
 - regExp - checks actual value with descriptor regExp.
 - function - checks actual value with descriptor function.
 
-Value for `checkMode` except `function` | `exists` | `notExists` can be array, so you can write even more complex logic. For example "does not contain these values" or "must be match to one of these regExp".
-
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/user',
@@ -251,12 +258,13 @@ const mockServerConfig = {
           {
             entities: {
               headers: {
-                // 'name-header' is 'Dmitriy' or 'Nursultan'
+                // 'name-header' is 'Dmitriy'
                 'name-header': {
                   checkMode: 'equals',
-                  value: ['Dmitriy', 'Nursultan']
+                  value: 'Dmitriy'
                 },
                 // check for 'equals' if descriptor not provided
+                // i.e. it is the same as `role: { checkMode: 'equals', value: 'developer' }`
                 role: 'developer'
               },
               cookies: {
@@ -264,32 +272,37 @@ const mockServerConfig = {
                 token: {
                   checkMode: 'exists'
                 },
-                // 'someSecretToken' cookie can be '123-abc' or 'abc-999' for example
+                // 'someSecretToken' cookie can be '123-abc' or '456-abc' for example
                 someSecretToken: {
                   checkMode: 'regExp',
-                  value: [/^\d\d\d-abc$/, /^abc-\d\d\d$/]
+                  value: /^\d\d\d-abc$/
                 }
               }
             },
-            data: 'Some user data for Dmitriy and Nursultan'
+            data: 'Some user data for Dmitriy'
           }
         ]
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-Also you can use array as value for REST body and GraphQL variables entities: in this case mock-config-server will iterate
-over array until `checkMode=equals` finds a match or return 404
+#### Descriptor _oneOf_ property
+
+For `checkMode` with the `value` property (all `checkMode` options except `exists` and `notExists`) you can use an array as value.
+Mock server will find matches by iterating through the array until **some** match is found.
+To be able to use this functionality you need to explicitly set `oneOf: true` property in descriptor object.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/user',
@@ -297,20 +310,37 @@ const mockServerConfig = {
         routes: [
           {
             entities: {
-              // if body equals to { key1: 'value1' } or ['value1'] then mock-config-server return data
-              body: [{ key1: 'value1' }, ['value1']]
+              // if body equals to { key1: 'value1' } OR { key2: 'value2' } then mock-config-server return 'Some user data 1'
+              body: {
+                checkMode: 'equals',
+                value: [{ key1: 'value1' }, { key2: 'value2' }],
+                oneOf: true
+              }
             },
-            data: 'Some user data'
+            data: 'Some user data 1'
+          },
+          {
+            entities: {
+              // if body equals to [{ key1: 'value1' }, { key2: 'value2' }] then mock-config-server return 'Some user data 2'
+              // NO `oneOf` => array processed entirely
+              body: {
+                checkMode: 'equals',
+                value: [{ key1: 'value1' }, { key2: 'value2' }]
+              }
+            },
+            data: 'Some user data 2'
           }
         ]
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+export default flatMockServerConfig;
 ```
 
+#### Function check mode
+
 `function checkMode` is the most powerful way to describe your `entities` logic, but in most cases you will be fine using other `checkModes`.
 
 `Function value` has the following signature `(actualValue, checkFunction) => boolean`.
@@ -320,10 +350,12 @@ You can use the `checkFunction` from second argument if you want to describe you
 `checkFunction` has the following signature `(checkMode, actualValue, descriptorValue?) => boolean`.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/posts/:postId',
@@ -340,7 +372,7 @@ const mockServerConfig = {
               cookies: {
                 authToken: {
                   checkMode: 'function',
-                  value: (actualValue, checkFunction) => 
+                  value: (actualValue, checkFunction) =>
                     checkFunction('equals', actualValue, 123) ||
                     checkFunction('startsWith', actualValue, 2)
                 }
@@ -352,21 +384,22 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+module.exports = flatMockServerConfig;
 ```
 
 ##### Using descriptors for part of REST body or GraphQL variables
 
-If you want to check a certain field of your body or variables, you can use descriptors in flatten object style. In this case server will check every field in entity with corresponding actual field.
-You can use descriptors for array body elements as well.
+If you want to check a deep nested property of your body or variables via descriptor you can use flatten object style. In this case server will check every field in entity with corresponding actual field. I.e. you can use descriptors only for properties of entity object (not for properties of nested objects).
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/users',
@@ -375,62 +408,35 @@ const mockServerConfig = {
           {
             entities: {
               body: {
-                'user.name': 'Sergey'
-              }
-            },
-            data: 'user.name in body is "Sergey"'
-          }
-        ]
-      },
-      {
-        path: '/posts',
-        method: 'post',
-        routes: [
-          {
-            entities: {
-              body: {
-                title: {
-                  checkMode: 'startsWith',
-                  value: 'A'
+                // if body has properties like { user: { name: 'Sergey' } } OR { 'user.name': 'Sergey' } then mock-config-server return data
+                'user.name': {
+                  checkMode: 'equals',
+                  value: 'Sergey'
                 }
               }
             },
-            data: 'title in body starts with "A"'
-          }
-        ]
-      },
-      {
-        path: '/posts',
-        method: 'post',
-        routes: [
-          {
-            entities: {
-              body: [
-                {
-                  checkMode: 'startsWith',
-                  value: 1
-                },
-                2
-              ]
-            },
-            data: 'array[0] starts with "1" and array[1] equals "2"'
+            data: 'user.name in body is "Sergey"'
           }
         ]
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-> To enable whole body/variables checking as plain object you should use descriptor for entire body/variables.
+You can also use descriptor for whole body or variables entity.
+
+> When you use 'equals'/'notEquals' check mode for whole body or variables mock-config-server is strictly compare entity and actual value. It means that you must specify **ALL** properties from actual body or variables.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/users',
@@ -439,6 +445,7 @@ const mockServerConfig = {
           {
             entities: {
               body: {
+                // if actual body contains some extra property(-ies) then this entity won't match
                 checkMode: 'equals',
                 value: {
                   user: {
@@ -455,131 +462,154 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-module.exports = mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-#### Polling
-
-Routes support polling for data. To add polling for data, you must specify the `polling setting` and change `data` property to `queue`.
+#### File responses
 
-> After receiving the last value from polling, the queue is reset and the next request will return the first value from the queue.
+Rest routes support paths to files. If a route is matched, the server will send data from the file. If the file is not found, the server will return 404.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
-        path: '/user',
+        path: '/files/settings',
         method: 'get',
         routes: [
           {
-            settings: { polling: true },
-            queue: [
-              { data: { emoji: '🦁', name: 'Nursultan' } },
-              { data: { emoji: '☄', name: 'Dmitriy' } }
-            ]
+            file: './settings.json'
           }
         ]
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-Using the additional `time` properties in milliseconds, you can specify how much time certain data should be returned
+> If the file path is absolute, then this path will be used as is. If the file path is relative, it will be appended to the current working directory.
+
+If the file exists, response interceptors will receive `file descriptor` as the `data` argument:
+
+`File descriptor` is an object with `path` and `file` fields that describe file location and file content.
+
+- `path` `string` path to the file. Same as `file` passed in route
+- `file` `Buffer` file content as binary buffer
+
+> Note to return file descriptor from interceptor. Server will send a buffer from `data.file` with corresponding `Content-Type` and `Content-Disposition` headers.
+> If you return invalid file descriptor, server will send it as json data.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
-        path: '/user',
+        path: '/files/settings',
         method: 'get',
         routes: [
           {
-            settings: { polling: true },
-            queue: [
-              { time: 5000, data: { emoji: '🦁', name: 'Nursultan' } },
-              { data: { emoji: '☄', name: 'Dmitriy' } }
-            ]
+            file: './settings.json',
+            interceptors: {
+              response: (data) => {
+                const { file, path } = data;
+                const buffer = file; // some logic with buffer
+                fs.writeFileSync(path, buffer); // rewrite ./settings.json file on disk with new content
+                return { path, file: buffer };
+              }
+            }
           }
         ]
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-#### File responses
+> Any changes to the data will not affect the file on disk unless you manually rewrite it.
 
-Rest routes support paths to files. If a route is matched, the server will send data from the file. If the file is not found, the server will return 404.
+> If you return a new `path` from interceptor, server will send file corresponding to this path or 404 error otherwise.
+
+#### Polling
+
+Routes support polling for data. To add polling for data, you must specify the `polling setting` and use `queue` property instead of `data` or `file`.
+
+`queue` is an array containing `data` or `file` that should be returned in order.
+
+> After receiving the last value from polling, the queue is reset and the next request will return the first value from the queue.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
-        path: '/files/settings',
+        path: '/user',
         method: 'get',
         routes: [
           {
-            file: './settings.json'
+            settings: { polling: true },
+            queue: [
+              { data: { emoji: '🦁', name: 'Nursultan' } },
+              { data: { emoji: '☄', name: 'Dmitriy' } },
+              { file: './users/Sergey.json' }
+            ]
           }
         ]
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-> If the file path is absolute, then this path will be used as is. If the file path is relative, it will be appended to the current working directory.
-
-If the file exists, response interceptors will receive null as the data argument.
+Using the additional `time` properties in milliseconds, you can specify how much time certain data should be returned
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
-        path: '/files/settings',
+        path: '/user',
         method: 'get',
         routes: [
           {
-            file: './settings.json',
-            interceptors: {
-              response: (data) => {
-                console.log(data); // null
-                return data;
-              }
-            }
+            settings: { polling: true },
+            queue: [
+              { time: 5000, data: { emoji: '🦁', name: 'Nursultan' } },
+              { data: { emoji: '☄', name: 'Dmitriy' } }
+            ]
           }
         ]
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
-> Any changes to the data will not affect the file (and the response, respectively).
-
 #### Static Path
 
 Entity for connecting statics to the server, like HTML, JSON, PNG, etc.
@@ -685,10 +715,12 @@ You can log requests and responses using `log` function in any [interceptor](#in
 `log` function returns object with logged token values
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/posts',
@@ -697,19 +729,23 @@ const mockServerConfig = {
           {
             interceptors: {
               request: ({ log }) => {
-                log({                 // logs following object in terminal
-                  options: {          // {
-                    id: true,         //  id: 1,
-                    type: true,       //  type: 'request',
-                    timestamp: true,  //  timestamp: '31.12.2024, 23:59:59,999',
-                    method: true,     //  method: 'GET',
-                    url: true         //  url: 'http://localhost:31299/api/rest/posts/1'
-                  }                   // }
+                log({
+                  // logs following object in terminal
+                  options: {
+                    // {
+                    id: true, //  id: 1,
+                    type: true, //  type: 'request',
+                    timestamp: true, //  timestamp: '31.12.2024, 23:59:59,999',
+                    method: true, //  method: 'GET',
+                    url: true //  url: 'http://localhost:31299/api/rest/posts/1'
+                  } // }
                 });
               },
               response: (data, { log }) => {
-                log({                 // logs following string in terminal
-                  options: {          // response get: http://localhost:31299/api/rest/posts/1 => 200
+                log({
+                  // logs following string in terminal
+                  options: {
+                    // response get: http://localhost:31299/api/rest/posts/1 => 200
                     type: true,
                     statusCode: true,
                     method: true,
@@ -727,15 +763,15 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
 > By default, `timestamp` and `method` tokens are prettified.
 > Timestamp transforms from UNIX-timestamp number to `DD.MM.YYYY, HH:mm:ss,sss` string.
 > Method transforms from lower case to upper case.
-> If `rewrite` function is used, those tokens will remain unformatted. You can format them as you need. 
+> If `rewrite` function is used, those tokens will remain unformatted. You can format them as you need.
 
 ##### Logger tokens
 
@@ -755,22 +791,25 @@ export default mockServerConfig;
 - `body?` `any` body
 
 Response logger has additional tokens
+
 - `statusCode?` `number` response status code
 - `data?` `any` data returned to client
 
 If you need to log specific properties in mapped entities (headers, cookies, query, params), use `Record<string, boolean>` object instead of boolean.
 In that case logger will use following logic:
 
-- if some token is `true`, entity will be filtered by `whitelist` logic. *Only* enabled ones will be logged.
-- if all tokens is `false`, entity will be filtered by `blacklist` logic. All entities will be logged *except* disabled ones.
+- if some token is `true`, entity will be filtered by `whitelist` logic. _Only_ enabled ones will be logged.
+- if all tokens is `false`, entity will be filtered by `blacklist` logic. All entities will be logged _except_ disabled ones.
 
 > Whitelist logic have priority over blacklist if you pass `true` and `false` in same entity.
 
 ```javascript
-/** @type {import('mock-config-server').MockServerConfig} */
-const mockServerConfig = {
-  rest: {
-    baseUrl: '/api',
+/** @type {import('mock-config-server').FlatMockServerConfig} */
+const flatMockServerConfig = [
+  {
+    baseUrl: '/api'
+  },
+  {
     configs: [
       {
         path: '/posts',
@@ -779,7 +818,8 @@ const mockServerConfig = {
           {
             interceptors: {
               request: ({ log }) => {
-                log({                 // whitelist. only query1 and query2 will be logged
+                log({
+                  // whitelist. only query1 and query2 will be logged
                   options: {
                     query: {
                       query1: true,
@@ -787,7 +827,8 @@ const mockServerConfig = {
                     }
                   }
                 });
-                log({                 // whitelist. only cookie1 and cookie2 will be logged
+                log({
+                  // whitelist. only cookie1 and cookie2 will be logged
                   options: {
                     cookies: {
                       cookie1: true,
@@ -796,7 +837,8 @@ const mockServerConfig = {
                     }
                   }
                 });
-                log({                 // blacklist. all headers will be logged except header1
+                log({
+                  // blacklist. all headers will be logged except header1
                   options: {
                     headers: {
                       header1: false
@@ -811,9 +853,9 @@ const mockServerConfig = {
       }
     ]
   }
-};
+];
 
-export default mockServerConfig;
+export default flatMockServerConfig;
 ```
 
 ## Database
@@ -826,16 +868,18 @@ With `mock-config-server` you can create your own mock database with all CRUD op
 ### Basic example
 
 ```javascript
-const mockServerConfig = {
-  database: {
-    data: {
-      users: [{ id: 1, name: 'John' }],
-      settings: {
-        blocked: false
+const flatMockServerConfig = [
+  {
+    database: {
+      data: {
+        users: [{ id: 1, name: 'John' }],
+        settings: {
+          blocked: false
+        }
       }
     }
   }
-};
+];
 ```
 
 Now you have the following routes for requests
@@ -872,20 +916,22 @@ __routes -> return routes from database config
 ### Routes example
 
 ```javascript
-const mockServerConfig = {
-  database: {
-    data: {
-      users: [{ id: 1, name: 'John' }],
-      settings: {
-        blocked: false
+const flatMockServerConfig = [
+  {
+    database: {
+      data: {
+        users: [{ id: 1, name: 'John' }],
+        settings: {
+          blocked: false
+        }
+      },
+      routes: {
+        '/api/users/:id': '/users/:id',
+        '/*/my-settings': '/settings'
       }
-    },
-    routes: {
-      '/api/users/:id': '/users/:id',
-      '/*/my-settings': '/settings'
     }
   }
-};
+];
 ```
 
 Now following routes will work correctly
@@ -986,12 +1032,14 @@ GET /users?_q=siberia&_q=24
 ### File example
 
 ```javascript
-const mockServerConfig = {
-  database: {
-    data: './data.json',
-    routes: './routes.json'
+const flatMockServerConfig = [
+  {
+    database: {
+      data: './data.json',
+      routes: './routes.json'
+    }
   }
-};
+];
 ```
 
 Instead of objects you can use paths to **JSON** files which contain needed data or routes