Port documentation changes from middyjs#371 (middyjs#376)

benjifs · May 21, 2020 · bc2a697 · bc2a697
1 parent 33027dc
commit bc2a697
Show file tree

Hide file tree

Showing 37 changed files with 102 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -379,6 +379,72 @@ const asyncValidator = () => {
 handler.use(asyncValidator())
 ```
 
+
+## Promises and error handling
+
+`onError` middlewares can return promises as well.
+Here's how Middy handles return values from promise-enabled error handlers:
+* If `onError` promise resolves to a *truthy* value, this value is treated as an error and passed further down the pipeline.
+
+```javascript
+middleware1 = {
+  onError: (handler) => {
+    Logger.debug("middleware1");
+    return Promise.resolve(handler.error)
+  }
+}
+middleware2 = {
+  onError: (handler) => {
+    Logger.debug("middleware2");
+    return Promise.resolve(handler.error)
+  }
+}
+handler.use(middleware1).use(middleware2);
+```
+
+Here, first `middleware1.onError` then `middleware2.onError` will be called.
+
+  - If the last `onError` in the chain returns a promise which resolves to a value, the lambda fails and reports an un-mamaged error
+  In the example above, the lambda will fail and report the error returned by `middleware2.onError`.
+  - If `onError` promise resolves to a *falsy* value (`null`, `undefined`, `false` etc.), the error handling pipeline exits early and the response is returned without an error
+
+```javascript
+middleware1 = {
+  onError: (handler) => {
+    handler.response = { error: handler.error };
+    return Promise.resolve();
+    // Resolves to a falsy value
+  }
+}
+middleware2 = {
+  onError: (handler) => {
+    return Promise.resolve(handler.error)
+  }
+}
+handler.use(middleware1).use(middleware2);
+```
+
+Here, only `middleware1.onError` will be called. The rest of the error handlers will be skipped, and the lambda will finish normally and return the response. `middleware2.onError` will not be called.
+
+  - If `onError` promise rejects, the error handling pipeline exists early and the lambda execution fails.
+
+```javascript
+middleware1 = {
+  onError: (handler) => {
+    return Promise.reject(handler.error);
+  }
+}
+middleware2 = {
+  onError: (handler) => {
+    return Promise.resolve(handler.error)
+  }
+}
+handler.use(middleware1).use(middleware2);
+```
+
+Here, only `middleware1.onError` will be called, and the lambda will fail early, reporting an error. `middleware2.onError` will not be called.
+
+
 ## Writing a middleware
 
 A middleware is an object that should contain at least 1 of 3 possible keys:

diff --git a/lerna.json b/lerna.json
@@ -3,5 +3,5 @@
   "packages": [
     "packages/*"
   ],
-  "version": "1.0.0-alpha.35"
+  "version": "1.0.0-alpha.36"
 }
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "middy-monorepo",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "🛵 The stylish Node.js middleware engine for AWS Lambda",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/cache/package.json b/packages/cache/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/cache",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Cache middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/core/package-lock.json b/packages/core/package-lock.json
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/core",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "🛵 The stylish Node.js middleware engine for AWS Lambda (core package)",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/do-not-wait-for-empty-event-loop/package.json b/packages/do-not-wait-for-empty-event-loop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/do-not-wait-for-empty-event-loop",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Middleware for the middy framework that allows to easily disable the wait for empty event loop in a Lambda function",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/error-logger/package-lock.json b/packages/error-logger/package-lock.json
diff --git a/packages/error-logger/package.json b/packages/error-logger/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/error-logger",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Input and output logger middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/function-shield/package-lock.json b/packages/function-shield/package-lock.json
diff --git a/packages/function-shield/package.json b/packages/function-shield/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/function-shield",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Hardens AWS Lambda execution environment",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-content-negotiation/package-lock.json b/packages/http-content-negotiation/package-lock.json
diff --git a/packages/http-content-negotiation/package.json b/packages/http-content-negotiation/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-content-negotiation",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http content negotiation middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-cors/package.json b/packages/http-cors/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-cors",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "CORS (Cross-Origin Resource Sharing) middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-error-handler/package-lock.json b/packages/http-error-handler/package-lock.json
diff --git a/packages/http-error-handler/package.json b/packages/http-error-handler/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-error-handler",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http error handler middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-event-normalizer/package.json b/packages/http-event-normalizer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-event-normalizer",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http event normalizer middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-header-normalizer/package.json b/packages/http-header-normalizer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-header-normalizer",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http header normalizer middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-json-body-parser/package-lock.json b/packages/http-json-body-parser/package-lock.json
diff --git a/packages/http-json-body-parser/package.json b/packages/http-json-body-parser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-json-body-parser",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http JSON body parser middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-partial-response/package-lock.json b/packages/http-partial-response/package-lock.json
diff --git a/packages/http-partial-response/package.json b/packages/http-partial-response/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-partial-response",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http partial response middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-response-serializer/package-lock.json b/packages/http-response-serializer/package-lock.json
diff --git a/packages/http-response-serializer/package.json b/packages/http-response-serializer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-response-serializer",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Http response serializer middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-security-header/package.json b/packages/http-security-header/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-security-header",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Applies best practice security headers to responses. It's a simplified port of HelmetJS",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/http-urlencode-body-parser/package-lock.json b/packages/http-urlencode-body-parser/package-lock.json
diff --git a/packages/http-urlencode-body-parser/package.json b/packages/http-urlencode-body-parser/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/http-urlencode-body-parser",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Urlencode body parser middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/input-output-logger/package-lock.json b/packages/input-output-logger/package-lock.json
diff --git a/packages/input-output-logger/package.json b/packages/input-output-logger/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/input-output-logger",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Input and output logger middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/s3-key-normalizer/package.json b/packages/s3-key-normalizer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/s3-key-normalizer",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "S3 key normalizer middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/secrets-manager/package-lock.json b/packages/secrets-manager/package-lock.json
diff --git a/packages/secrets-manager/package.json b/packages/secrets-manager/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/secrets-manager",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Secrets Manager middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/ssm/package-lock.json b/packages/ssm/package-lock.json
diff --git a/packages/ssm/package.json b/packages/ssm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/ssm",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "SSM (EC2 Systems Manager) parameters middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/validator/package-lock.json b/packages/validator/package-lock.json
diff --git a/packages/validator/package.json b/packages/validator/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/validator",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Validator middleware for the middy framework",
   "engines": {
     "node": ">=6.10"

diff --git a/packages/warmup/package.json b/packages/warmup/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@middy/warmup",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.36",
   "description": "Warmup (cold start mitigation) middleware for the middy framework",
   "engines": {
     "node": ">=6.10"