feat(server): use async and dep updates

- Replace promise-based code with async/await. - Update dependencies, notably Hapi 17 - Update docma configuration for better outpout - **[Breaking change]**: `startServer()` used to throw synrchonous errors while validating configuration. Now all errors are thrown asynchronously
feugy · Feb 11, 2018 · 7d7ce86 · 7d7ce86
1 parent f011f1a
commit 7d7ce86
Show file tree

Hide file tree

Showing 10 changed files with 235 additions and 236 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,17 +1,23 @@
 
 # Changelog
 
+## 4.0.0
+- Use async/await instead of promise-based code. Requires node@8+
+- **[Breaking change]**: `startServer()` used to throw synrchonous errors while validating configuration.
+   Now all errors are thrown asynchronously
+- Dependencies update, including Hapi 17
+
 ## 3.3.1
-- fix max request payload limit by configuring it to a GB.
-- dependencies update
+- Fix max request payload limit by configuring it to a GB.
+- Dependencies update
 
 ## 3.3.0
-- expose customizable OpenAPI descriptor (disabled by default)
-- allow default values for API parameters
-- allow documentation and validation of API result (disabled by default)
+- Expose customizable OpenAPI descriptor (disabled by default)
+- Allow default values for API parameters
+- Allow documentation and validation of API result (disabled by default)
 
 ## 3.2.1
-- disabled low-level socket timeout
+- Disabled low-level socket timeout
 
 ## 3.2.0
 - Support synchronous `init()` and API functions

diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ mini-service uses the latest ES6 features, so it requires node 6+
 Here is a simple calculator service definition, that exposes functions to add and subtract numbers.
 
 `calc-service.js`
-```javascript
+```js
 module.exports = {
   name: 'calc-service',
   version: '1.0.0',
@@ -47,7 +47,7 @@ If you want to use it locally in a different file:
 require the service definition, and create a [mini-client][mini-client-url] with it
 
 `caller-local.js`
-```javascript
+```js
 const {getClient} = require('mini-service')
 const calcService = require('./calc-service')
 
@@ -57,7 +57,7 @@ const calc = getClient(calcService)
 Then, init it (it's an async operation) and invoke any exposed API you need:
 
 `caller-local.js`
-```javascript
+```js
 await calc.init()
 const sum = await calc.add(10, 5)
 console.log(`Result is: ${sum}`)
@@ -67,7 +67,7 @@ Now let's imagine you need to deploy your calculator service in a standalone Htt
 To turn your local service into a real server, expose your service definition with mini-service's `startServer()`:
 
 `calc-service.js`
-```javascript
+```js
 const {startServer} = require('mini-service')
 
 module.exports = {...} // same service definition as above
@@ -79,7 +79,7 @@ A server is now listening on port 3000.
 And to use it from a remote caller, creates a mini-client giving the proper url:
 
 `caller-remote.js`
-```javascript
+```js
 const getClient = require('mini-client') // or: const {getClient} = require('mini-service')
 
 const calc = getClient({
@@ -91,7 +91,7 @@ Please note that you **don't need to require the service definition anymore**.
 Usage is exactly the same as previously.
 
 `caller-remote.js`
-```javascript
+```js
 await calc.init() // no-op, can be skipped
 const sum = await calc.add(10, 5)
 console.log(`Result is: ${sum}`)
@@ -108,7 +108,16 @@ This project was kindly sponsored by [nearForm][nearform].
 Copyright [Damien Simonin Feugas][feugy] and other contributors, licensed under [MIT](./LICENSE).
 
 
-## 2.x to 3.x changes
+## 3.x to 4.x migration
+
+Version 4 is using async/await, which requires node@8+.
+
+The only breaking change is on `startServer()`:
+- previously it threw synrchonous errors while validating configuration.
+- now all errors are thrown asynchronously
+
+
+## 2.x to 3.x migration
 
 Groups are now used as sub-objects of mini-client.
 
@@ -118,7 +127,7 @@ Given a service exposing:
 - group `b` with api `ping`
 
 the final Mini-client will be:
-```javascript
+```js
 client = {
   ping(),
   a: {
@@ -132,13 +141,13 @@ client = {
 ```
 
 
-## 1.x to 2.x changes
+## 1.x to 2.x migration
 
 Local services, as remote services, **must** have `name` and `version` options defined
 
 When loading services, the `services` property was renamed to `groups`, and `serviceOpts` is now `groupOpts`:
 
-```javascript
+```js
 const {startServer} = require('mini-service')
 
 startServer({

diff --git a/docma.config.json b/docma.config.json
@@ -7,10 +7,9 @@
   ],
   "dest": "./docs",
   "jsdoc": {
-    "allowUnknownTags": false,
+    "allowUnknownTags": true,
     "hierarchy": true,
-    "recurse": true,
-    "sort": "grouped"
+    "recurse": true
   },
   "app": {
     "title": "Mini-service documentation",
@@ -19,9 +18,9 @@
   },
   "template": {
     "path": "default",
-    "outline": "flat",
     "options": {
       "title": "mini-service",
+      "outline": "tree",
       "navItems": [{
         "iconClass": "glyphicon glyphicon-map-marker",
         "label": "Welcome",

diff --git a/docs/content/changelog.html b/docs/content/changelog.html
@@ -1,15 +1,22 @@
 
 <html><head></head><body><h1 id="changelog">Changelog</h1>
 <hr />
+<h2 id="4-0-0">4.0.0</h2>
+<ul>
+<li>Use async/await instead of promise-based code. Requires node@8+</li>
+<li><strong>[Breaking change]</strong>: <code>startServer()</code> used to throw synrchonous errors while validating configuration.
+ Now all errors are thrown asynchronously</li>
+<li>Dependencies update, including Hapi 17</li>
+</ul>
 <h2 id="3-3-0">3.3.0</h2>
 <ul>
-<li>expose customizable OpenAPI descriptor (disabled by default)</li>
-<li>allow default values for API parameters</li>
-<li>allow documentation and validation of API result (disabled by default)</li>
+<li>Expose customizable OpenAPI descriptor (disabled by default)</li>
+<li>Allow default values for API parameters</li>
+<li>Allow documentation and validation of API result (disabled by default)</li>
 </ul>
 <h2 id="3-2-1">3.2.1</h2>
 <ul>
-<li>disabled low-level socket timeout</li>
+<li>Disabled low-level socket timeout</li>
 </ul>
 <h2 id="3-2-0">3.2.0</h2>
 <ul>

diff --git a/docs/content/readme.html b/docs/content/readme.html
@@ -26,7 +26,7 @@ <h2 id="introduction">Introduction</h2>
 <h2 id="example">Example</h2>
 <p>Here is a simple calculator service definition, that exposes functions to add and subtract numbers.</p>
 <p><code>calc-service.js</code></p>
-<pre><code class="lang-javascript">module.exports = {
+<pre><code class="lang-js">module.exports = {
   name: 'calc-service',
   version: '1.0.0',
   init: () =&gt; {
@@ -39,21 +39,21 @@ <h2 id="example">Example</h2>
 <p>If you want to use it locally in a different file:
 require the service definition, and create a [mini-client][mini-client-url] with it</p>
 <p><code>caller-local.js</code></p>
-<pre><code class="lang-javascript">const {getClient} = require('mini-service')
+<pre><code class="lang-js">const {getClient} = require('mini-service')
 const calcService = require('./calc-service')
 
 const calc = getClient(calcService)
 </code></pre>
 <p>Then, init it (it's an async operation) and invoke any exposed API you need:</p>
 <p><code>caller-local.js</code></p>
-<pre><code class="lang-javascript">await calc.init()
+<pre><code class="lang-js">await calc.init()
 const sum = await calc.add(10, 5)
 console.log(`Result is: ${sum}`)
 </code></pre>
 <p>Now let's imagine you need to deploy your calculator service in a standalone Http server, and invoke it from a remote server.
 To turn your local service into a real server, expose your service definition with mini-service's <code>startServer()</code>:</p>
 <p><code>calc-service.js</code></p>
-<pre><code class="lang-javascript">const {startServer} = require('mini-service')
+<pre><code class="lang-js">const {startServer} = require('mini-service')
 
 module.exports = {...} // same service definition as above
 // starts Http server
@@ -62,7 +62,7 @@ <h2 id="example">Example</h2>
 <p>A server is now listening on port 3000.</p>
 <p>And to use it from a remote caller, creates a mini-client giving the proper url:</p>
 <p><code>caller-remote.js</code></p>
-<pre><code class="lang-javascript">const getClient = require('mini-client') // or: const {getClient} = require('mini-service')
+<pre><code class="lang-js">const getClient = require('mini-client') // or: const {getClient} = require('mini-service')
 
 const calc = getClient({
   remote: 'http://localhost:3000'
@@ -71,15 +71,22 @@ <h2 id="example">Example</h2>
 <p>Please note that you <strong>don't need to require the service definition anymore</strong>.</p>
 <p>Usage is exactly the same as previously.</p>
 <p><code>caller-remote.js</code></p>
-<pre><code class="lang-javascript">await calc.init() // no-op, can be skipped
+<pre><code class="lang-js">await calc.init() // no-op, can be skipped
 const sum = await calc.add(10, 5)
 console.log(`Result is: ${sum}`)
 </code></pre>
 <h2 id="acknowledgements">Acknowledgements</h2>
 <p>This project was kindly sponsored by <a href="http://nearform.com">nearForm</a>.</p>
 <h2 id="license">License</h2>
 <p>Copyright <a href="https://github.com/feugy">Damien Simonin Feugas</a> and other contributors, licensed under <a href="./LICENSE">MIT</a>.</p>
-<h2 id="2-x-to-3-x-changes">2.x to 3.x changes</h2>
+<h2 id="3-x-to-4-x-migration">3.x to 4.x migration</h2>
+<p>Version 4 is using async/await, which requires node@8+.</p>
+<p>The only breaking change is on <code>startServer()</code>:</p>
+<ul>
+<li>previously it threw synrchonous errors while validating configuration.</li>
+<li>now all errors are thrown asynchronously</li>
+</ul>
+<h2 id="2-x-to-3-x-migration">2.x to 3.x migration</h2>
 <p>Groups are now used as sub-objects of mini-client.</p>
 <p>Given a service exposing:</p>
 <ul>
@@ -88,7 +95,7 @@ <h2 id="2-x-to-3-x-changes">2.x to 3.x changes</h2>
 <li>group <code>b</code> with api <code>ping</code></li>
 </ul>
 <p>the final Mini-client will be:</p>
-<pre><code class="lang-javascript">client = {
+<pre><code class="lang-js">client = {
   ping(),
   a: {
     ping(),
@@ -99,10 +106,10 @@ <h2 id="2-x-to-3-x-changes">2.x to 3.x changes</h2>
   }
 }
 </code></pre>
-<h2 id="1-x-to-2-x-changes">1.x to 2.x changes</h2>
+<h2 id="1-x-to-2-x-migration">1.x to 2.x migration</h2>
 <p>Local services, as remote services, <strong>must</strong> have <code>name</code> and <code>version</code> options defined</p>
 <p>When loading services, the <code>services</code> property was renamed to <code>groups</code>, and <code>serviceOpts</code> is now <code>groupOpts</code>:</p>
-<pre><code class="lang-javascript">const {startServer} = require('mini-service')
+<pre><code class="lang-js">const {startServer} = require('mini-service')
 
 startServer({
   groups: [ // was services previously

diff --git a/docs/js/docma-web.js b/docs/js/docma-web.js
diff --git a/lib/index.js b/lib/index.js
@@ -6,7 +6,8 @@ module.exports = {
 
   /**
    * Starts a server using given service definition(s).
-   * @see {@link #module:server~startServer|module:server.startServer}
+   * @async
+   * @see {@link #module:server}
    */
   startServer: require('./server'),