Rework implementation with initial .cause support

API.md

@@ -27,44 +27,37 @@ Rebuilds `error.output` using the other object properties where:
 
 - `debug` - a Boolean that, when `true`, causes Internal Server Error messages to be left in tact. Defaults to `false`, meaning that Internal Server Error messages are redacted.
 
-Note that `Boom` object will return `true` when used with `instanceof Boom`, but do not use the
-`Boom` prototype (they are either plain `Error` or the error prototype passed in). This means
-`Boom` objects should only be tested using `instanceof Boom` or `Boom.isBoom()` but not by looking
-at the prototype or contructor information. This limitation is to avoid manipulating the prototype
-chain which is very slow.
-
 #### Helper Methods
 
 ##### `new Boom.Boom(message, [options])`
 
-Creates a new `Boom` object using the provided `message` and then calling
-[`boomify()`](#boomifyerr-options) to decorate the error with the `Boom` properties, where:
-- `message` - the error message. If `message` is an error, it is the same as calling
-  [`boomify()`](#boomifyerr-options) directly.
+Creates a new `Boom` object, where:
+- `message` - the error message.
 - `options` - and optional object where:
-	- `statusCode` - the HTTP status code. Defaults to `500` if no status code is already set.
+	- `statusCode` - the HTTP status code. Defaults to `500`.
+ 	- `cause` - The error that caused the boom error.
     - `data` - additional error information (assigned to `error.data`).
     - `decorate` - an option with extra properties to set on the error object.
     - `ctor` - constructor reference used to crop the exception call stack output.
-    - if `message` is an error object, also supports the other [`boomify()`](#boomifyerr-options)
-      options.
 
 ##### `boomify(err, [options])`
 
-Decorates an error with the `Boom` properties where:
+This works as [`new Boom.Boom()`](#new-boomboommessage-options), except when the `err` argument is a boom error.
+In that case, it will apply the options to the existing error, instead of wrapping it in a new boom error.
+Decorates a boom object with the `Boom` properties where:
 - `err` - the `Error` object to decorate.
 - `options` - optional object with the following optional settings:
 	- `statusCode` - the HTTP status code. Defaults to `500` if no status code is already set and `err` is not a `Boom` object.
 	- `message` - error message string. If the error already has a message, the provided `message` is added as a prefix.
-	  Defaults to no message.
     - `decorate` - an option with extra properties to set on the error object.
 	- `override` - if `false`, the `err` provided is a `Boom` object, and a `statusCode` or `message` are provided,
 	  the values are ignored. Defaults to `true` (apply the provided `statusCode` and `message` options to the error
 	  regardless of its type, `Error` or `Boom` object).
+- it returns the boomified error
 
 ```js
-var error = new Error('Unexpected input');
-Boom.boomify(error, { statusCode: 400 });
+const error = new Error('Unexpected input');
+const boomified = Boom.boomify(error, { statusCode: 400 });
 ```
 
 ##### `isBoom(err, [statusCode])`
@@ -108,7 +101,8 @@ Returns a 401 Unauthorized error where:
   - an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
 - `attributes` - an object of values to use while setting the 'WWW-Authenticate' header. This value is only used
   when `scheme` is a string, otherwise it is ignored. Every key/value pair will be included in the
-  'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under the `attributes` key.  Alternatively value can be a string which is use to set the value of the scheme, for example setting the token value for negotiate header.  If string is used message parameter must be null.
+  'WWW-Authenticate' in the format of 'key="value"'. Alternatively value can be a string which is used to set the
+  value of the scheme, for example setting the token value for negotiate header.  If string is used message parameter must be null.
   `null` and `undefined` will be replaced with an empty string. If `attributes` is set, `message` will be used as
   the 'error' segment of the 'WWW-Authenticate' header. If `message` is unset, the 'error' segment of the header
   will not be present and `isMissing` will be true on the error object.
@@ -141,10 +135,7 @@ Generates the following response:
 "payload": {
     "statusCode": 401,
     "error": "Unauthorized",
-    "message": "invalid password",
-    "attributes": {
-        "error": "invalid password"
-    }
+    "message": "invalid password"
 },
 "headers": {
   "WWW-Authenticate": "sample error=\"invalid password\""
@@ -160,8 +151,7 @@ Generates the following response:
 ```json
 "payload": {
     "statusCode": 401,
-    "error": "Unauthorized",
-    "attributes": "VGhpcyBpcyBhIHRlc3QgdG9rZW4="
+    "error": "Unauthorized"
 },
 "headers": {
   "WWW-Authenticate": "Negotiate VGhpcyBpcyBhIHRlc3QgdG9rZW4="
@@ -178,13 +168,7 @@ Generates the following response:
 "payload": {
     "statusCode": 401,
     "error": "Unauthorized",
-    "message": "invalid password",
-    "attributes": {
-        "error": "invalid password",
-        "ttl": 0,
-        "cache": "",
-        "foo": "bar"
-    }
+    "message": "invalid password"
 },
 "headers": {
   "WWW-Authenticate": "sample ttl=\"0\", cache=\"\", foo=\"bar\", error=\"invalid password\""