Merge pull request hapijs#203 from sloria/hapi17-docs

Update docs for hapi 17
peteclark3 · Nov 24, 2017 · 87a583c · 87a583c
2 parents 122f77c + 16f5e5e
commit 87a583c
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 78 deletions.
diff --git a/API.md b/API.md
@@ -1,4 +1,4 @@
-# 6.4.x API Reference
+# 7.0.x API Reference
 
 - [Registration](#registration)
 - [Server](#server)
@@ -13,9 +13,9 @@
     - [`socket.server`](#socketserver)
     - [`socket.connection`](#socketconnection)
     - [`socket.disconnect()`](#socketdisconnect)
-    - [`socket.send(message, [callback])`](#socketsendmessage-callback)
-    - [`socket.publish(path, message, [callback])`](#socketpublishpath-message-callback)
-    - [`socket.revoke(path, message, [callback])`](#socketrevokepath-message-callback)
+    - [`await socket.send(message)`](#socketsendmessage-callback)
+    - [`await socket.publish(path, message)`](#socketpublishpath-message-callback)
+    - [`await socket.revoke(path, message)`](#socketrevokepath-message-callback)
 - [Request](#request)
     - [`request.socket`](#requestsocket)
 - [Client](#client)
@@ -24,13 +24,13 @@
     - [`client.onConnect`](#clientonconnect)
     - [`client.onDisconnect`](#clientondisconnect)
     - [`client.onUpdate`](#clientonupdate)
-    - [`client.connect([options], callback)`](#clientconnectoptions-callback)
-    - [`client.disconnect([callback])`](#clientdisconnectcallback)
+    - [`await client.connect([options])`](#clientconnectoptions-callback)
+    - [`await client.disconnect()`](#clientdisconnectcallback)
     - [`client.id`](#clientid)
-    - [`client.request(options, callback)`](#clientrequestoptions-callback)
-    - [`client.message(message, callback)`](#clientmessagemessage-callback)
-    - [`client.subscribe(path, handler, callback)`](#clientsubscribepath-handler-callback)
-    - [`client.unsubscribe(path, handler, callback)`](#clientunsubscribepath-handler-callback)
+    - [`await client.request(options)`](#clientrequestoptions-callback)
+    - [`await client.message(message)`](#clientmessagemessage-callback)
+    - [`await client.subscribe(path, handler)`](#clientsubscribepath-handler-callback)
+    - [`await client.unsubscribe(path, handler)`](#clientunsubscribepath-handler-callback)
     - [`client.subscriptions()`](#clientsubscriptions)
     - [`client.overrideReconnectionAuth(auth)`](#clientoverriderecinnectionauthauth)
     - [Errors](#errors)
@@ -265,40 +265,32 @@ The socket's server reference.
 
 The socket's connection reference.
 
-### `socket.disconnect([callback])`
+### `socket.disconnect()`
 
-Closes a client connection where:
-- `callback` - optional callback for when the connection is fully closed using the signature
-  `function()`.
+Closes a client connection.
 
-### `socket.send(message, [callback])`
+### `await socket.send(message)`
 
 Sends a custom message to the client where:
 - `message` - the message sent to the client. Can be any type which can be safely converted to
   string using `JSON.stringify()`.
-- `callback` - optional callback method using signature `function(err)` where:
-    - `err` - an error condition.
 
-### `socket.publish(path, message, [callback])`
+### `await socket.publish(path, message)`
 
 Sends a subscription update to a specific client where:
 - `path` - the subscription string. Note that if the client did not subscribe to the provided `path`,
   the client will ignore the update silently.
 - `message` - the message sent to the client. Can be any type which can be safely converted to
   string using `JSON.stringify()`.
-- `callback` - optional callback method using signature `function(err)` where:
-    - `err` - an error condition.
 
-### `socket.revoke(path, message, [callback])`
+### `await socket.revoke(path, message)`
 
 Revokes a subscription and optionally includes a last update where:
 - `path` - the subscription string. Note that if the client is not subscribe to the provided `path`,
   the client will ignore the it silently.
 - `message` - an optional last subscription update sent to the client. Can be any type which can be
   safely converted to string using `JSON.stringify()`. Pass `null` to revoke the subscription without
   sending a last update.
-- `callback` - optional callback method using signature `function(err)` where:
-    - `err` - an error condition.
 
 ## Request
 
@@ -349,7 +341,7 @@ where:
 A property used to set a custom message handler with the signature `function(message)`. Invoked whenever
 the server calls `server.broadcast()` or `socket.send()`.
 
-### `client.connect([options], callback)`
+### `await client.connect([options])`
 
 Connects the client to the server where:
 - `options` - an optional configuration object with the following options:
@@ -367,10 +359,8 @@ Connects the client to the server where:
     - `retries` - number of reconnection attempts. Defaults to `Infinity` (unlimited).
     - `timeout` - socket connection timeout in milliseconds. Defaults to the WebSocket
       implementation timeout default.
-- `callback` - the server response callback using the signature `function(err)` where:
-    - `err` - an error response.
 
-### `client.disconnect()`
+### `await client.disconnect()`
 
 Disconnects the client from the server and stops future reconnects.
 
@@ -379,7 +369,7 @@ Disconnects the client from the server and stops future reconnects.
 The unique socket identifier assigned by the server. The value is set after the connection is
 established.
 
-### `client.request(options, callback)`
+### `client.request(options)`
 
 Sends an endpoint request to the server where:
 - `options` - value can be one of:
@@ -391,24 +381,20 @@ Sends an endpoint request to the server where:
         - `headers` - an object where each key is a request header and the value the header
           content. Cannot include an Authorization header. Defaults to no headers.
         - `payload` - the request payload sent to the server.
-- `callback` - the callback method using the signature `function(err, payload, statusCode, headers)`
   where:
     - `err` - the `Error` condition if the request failed.
     - `payload` - the server response object.
     - `statusCode` - the HTTP response status code.
     - `headers` - an object containing the HTTP response headers returned by the server (based on
       the server configuration).
 
-### `client.message(message, callback)`
+### `await client.message(message)`
 
 Sends a custom message to the server which is received by the server `onMessage` handler where:
 - `message` - the message sent to the server. Can be any type which can be safely converted to
   string using `JSON.stringify()`.
-- `callback` - the server response callback using the signature `function(err, message)` where:
-    - `err` - an error response.
-    - `message` - the server response if no error occurred.
 
-### `client.subscribe(path, handler, callback)`
+### `await client.subscribe(path, handler)`
 
 Subscribes to a server subscription where:
 - `path` - the requested subscription path. Paths are just like HTTP request paths (e.g.
@@ -419,22 +405,16 @@ Subscribes to a server subscription where:
     - `flags` - an object with the following optional flags:
         - `revoked` - set to `true` when the message is the last update from the server due to
           a subscription revocation.
-- `callback` - the callback function called when the subscription request was received by the server
-  or failed to transmit using the signature `function(err)` where:
-    - `err` - if present, indicates the subscription request has failed.
 
 Note that when `subscribe()` is called before the client connects, any server errors will be
 received via the `connect()` callback.
 
-### `client.unsubscribe(path, handler, callback)`
+### `await client.unsubscribe(path, handler)`
 
 Cancels a subscription where:
 - `path` - the subscription path used to subscribe.
 - `handler` - remove a specific handler from a subscription or `null` to remove all handlers for
   the given path.
-- `callback` - the callback function called when the subscription request was received by the server
-  or failed to transmit using the signature `function(err)` where:
-    - `err` - if present, indicates the request has failed.
 
 ### `client.subscriptions()`
 

diff --git a/README.md b/README.md
@@ -40,10 +40,9 @@ var Hapi = require('hapi');
 var Nes = require('nes');
 
 var server = new Hapi.Server();
-server.connection();
-
-server.register(Nes, function (err) {
 
+const start = async () => {
+    await server.register(Nes);
     server.route({
         method: 'GET',
         path: '/h',
@@ -55,9 +54,9 @@ server.register(Nes, function (err) {
             }
         }
     });
-
-    server.start(function (err) { /* ... */ });
-});
+    await server.start();
+};
+start();
 ```
 
 #### Client
@@ -66,10 +65,8 @@ server.register(Nes, function (err) {
 var Nes = require('nes');
 
 var client = new Nes.Client('ws://localhost');
-client.connect(function (err) {
-
+client.connect().then(() => {
     client.request('hello', function (err, payload) {   // Can also request '/h'
-
         // payload -> 'world!'
     });
 });
@@ -84,14 +81,11 @@ var Hapi = require('hapi');
 var Nes = require('nes');
 
 var server = new Hapi.Server();
-server.connection();
-
-server.register(Nes, function (err) {
 
+server.register(Nes).then(() => {
     server.subscription('/item/{id}');
 
     server.start(function (err) {
-
         server.publish('/item/5', { id: 5, status: 'complete' });
         server.publish('/item/6', { id: 6, status: 'initial' });
     });
@@ -104,8 +98,7 @@ server.register(Nes, function (err) {
 var Nes = require('nes');
 
 var client = new Nes.Client('ws://localhost');
-client.connect(function (err) {
-
+client.connect().then(() => {
     var handler = function (update, flags) {
 
         // update -> { id: 5, status: 'complete' }
@@ -125,12 +118,9 @@ var Hapi = require('hapi');
 var Nes = require('nes');
 
 var server = new Hapi.Server();
-server.connection();
-
-server.register(Nes, function (err) {
 
+server.register(Nes).then(() => {
     server.start(function (err) {
-
         server.broadcast('welcome!');
     });
 });
@@ -142,10 +132,8 @@ server.register(Nes, function (err) {
 var Nes = require('nes');
 
 var client = new Nes.Client('ws://localhost');
-client.connect(function (err) {
-
+client.connect().then(() => {
     client.onUpdate = function (update) {
-
         // update -> 'welcome!'
     };
 });
@@ -162,9 +150,8 @@ var Bcrypt = require('bcrypt');
 var Nes = require('nes');
 
 var server = new Hapi.Server();
-server.connection();
 
-server.register([Basic, Nes], function (err) {
+server.register([Basic, Nes]).then(async () => {
 
     // Set up HTTP Basic authentication
 
@@ -206,7 +193,7 @@ server.register([Basic, Nes], function (err) {
         }
     });
 
-    server.start(function (err) { /* ... */ });
+    await server.start();
 });
 ```
 
@@ -216,10 +203,8 @@ server.register([Basic, Nes], function (err) {
 var Nes = require('nes');
 
 var client = new Nes.Client('ws://localhost');
-client.connect({ auth: { headers: { authorization: 'Basic am9objpzZWNyZXQ=' } } }, function (err) {
-
+client.connect({ auth: { headers: { authorization: 'Basic am9objpzZWNyZXQ=' } } }).then(() => {
     client.request('hello', function (err, payload) {   // Can also request '/h'
-
         // payload -> 'Hello John Doe'
     });
 });
@@ -236,9 +221,8 @@ var Bcrypt = require('bcrypt');
 var Nes = require('nes');
 
 var server = new Hapi.Server();
-server.connection();
 
-server.register([Basic, Nes], function (err) {
+server.register([Basic, Nes]).then(async () => {
 
     // Set up HTTP Basic authentication
 
@@ -275,11 +259,9 @@ server.register([Basic, Nes], function (err) {
         }
     });
 
-    server.start(function (err) {
-
-        server.publish('/items', { id: 5, status: 'complete', updater: 'john' });
-        server.publish('/items', { id: 6, status: 'initial', updater: 'steve' });
-    });
+    await server.start();
+    server.publish('/items', { id: 5, status: 'complete', updater: 'john' });
+    server.publish('/items', { id: 6, status: 'initial', updater: 'steve' });
 });
 ```
 
@@ -292,15 +274,15 @@ var client = new Nes.Client('ws://localhost');
 
 // Authenticate as 'john'
 
-client.connect({ auth: { headers: { authorization: 'Basic am9objpzZWNyZXQ=' } } }, function (err) {
+client.connect({ auth: { headers: { authorization: 'Basic am9objpzZWNyZXQ=' } } }).then(() => {
 
     var handler = function (err, update) {
 
         // First publish is not received (filtered due to updater key)
         // update -> { id: 6, status: 'initial', updater: 'steve' }
     };
 
-    client.subscribe('/items', handler, function (err) { });
+    client.subscribe('/items', handler);
 });
 ```