From bc2a697727001714ed97f0a6c4b5da18a5f5aaf5 Mon Sep 17 00:00:00 2001 From: Luciano Mammino Date: Sat, 10 Aug 2019 15:22:39 +0100 Subject: [PATCH] Port documentation changes from #371 (#376) --- README.md | 66 +++++++++++++++++++ lerna.json | 2 +- package.json | 2 +- packages/cache/package.json | 2 +- packages/core/package-lock.json | 2 +- packages/core/package.json | 2 +- .../package.json | 2 +- packages/error-logger/package-lock.json | 2 +- packages/error-logger/package.json | 2 +- packages/function-shield/package-lock.json | 2 +- packages/function-shield/package.json | 2 +- .../package-lock.json | 2 +- .../http-content-negotiation/package.json | 2 +- packages/http-cors/package.json | 2 +- packages/http-error-handler/package-lock.json | 2 +- packages/http-error-handler/package.json | 2 +- packages/http-event-normalizer/package.json | 2 +- packages/http-header-normalizer/package.json | 2 +- .../http-json-body-parser/package-lock.json | 2 +- packages/http-json-body-parser/package.json | 2 +- .../http-partial-response/package-lock.json | 2 +- packages/http-partial-response/package.json | 2 +- .../package-lock.json | 2 +- .../http-response-serializer/package.json | 2 +- packages/http-security-header/package.json | 2 +- .../package-lock.json | 2 +- .../http-urlencode-body-parser/package.json | 2 +- .../input-output-logger/package-lock.json | 2 +- packages/input-output-logger/package.json | 2 +- packages/s3-key-normalizer/package.json | 2 +- packages/secrets-manager/package-lock.json | 2 +- packages/secrets-manager/package.json | 2 +- packages/ssm/package-lock.json | 2 +- packages/ssm/package.json | 2 +- packages/validator/package-lock.json | 2 +- packages/validator/package.json | 2 +- packages/warmup/package.json | 2 +- 37 files changed, 102 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 9159a17e9..4a31755f7 100644 --- 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 index db3eb75ef..e6e178043 100644 --- 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 index ccf4e0825..3deb19c8c 100644 --- 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 index c173bf696..42e4585eb 100644 --- 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 index 4897935fa..65b23681f 100644 --- a/packages/core/package-lock.json +++ b/packages/core/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/core", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/core/package.json b/packages/core/package.json index 9627fcb21..7e8567fb5 100644 --- 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 index 3e5463647..819d721e1 100644 --- 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 index 0e7bb2458..4c02e9393 100644 --- a/packages/error-logger/package-lock.json +++ b/packages/error-logger/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/error-logger", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/error-logger/package.json b/packages/error-logger/package.json index 39efaa5a1..d3d9e511b 100644 --- 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 index 72a25057a..66d45dc4e 100644 --- a/packages/function-shield/package-lock.json +++ b/packages/function-shield/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/function-shield", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/function-shield/package.json b/packages/function-shield/package.json index f866dd861..56217eb22 100644 --- 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 index 2cc143a3f..61a9bda50 100644 --- a/packages/http-content-negotiation/package-lock.json +++ b/packages/http-content-negotiation/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/http-content-negotiation", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/http-content-negotiation/package.json b/packages/http-content-negotiation/package.json index fbdf7be37..0cdf10a21 100644 --- 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 index 9472d071c..c2c052a9c 100644 --- 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 index 172ff5ea3..27a8e217c 100644 --- a/packages/http-error-handler/package-lock.json +++ b/packages/http-error-handler/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/http-error-handler", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/http-error-handler/package.json b/packages/http-error-handler/package.json index 428aadd9e..ab5cbec0e 100644 --- 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 index 1a9a45473..9e1e33e32 100644 --- 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 index 84027775b..42d6d1110 100644 --- 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 index d20faf800..eb148d50e 100644 --- a/packages/http-json-body-parser/package-lock.json +++ b/packages/http-json-body-parser/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/http-json-body-parser", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/http-json-body-parser/package.json b/packages/http-json-body-parser/package.json index e58ab7bc2..9daab773b 100644 --- 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 index 0c8e531ac..2ffd6bc2b 100644 --- a/packages/http-partial-response/package-lock.json +++ b/packages/http-partial-response/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/http-partial-response", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/http-partial-response/package.json b/packages/http-partial-response/package.json index 814b9c4ce..7bc5074be 100644 --- 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 index 9a7a00a68..1001495d1 100644 --- a/packages/http-response-serializer/package-lock.json +++ b/packages/http-response-serializer/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/http-response-serializer", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/http-response-serializer/package.json b/packages/http-response-serializer/package.json index ea52e29b0..cbab85e97 100644 --- 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 index 5bf431a69..4327f8e46 100644 --- 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 index 4ec104ca8..21e64c5a6 100644 --- a/packages/http-urlencode-body-parser/package-lock.json +++ b/packages/http-urlencode-body-parser/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/http-urlencode-body-parser", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/http-urlencode-body-parser/package.json b/packages/http-urlencode-body-parser/package.json index 6679167f9..4f5bac5e2 100644 --- 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 index c027f7550..83100e6bf 100644 --- a/packages/input-output-logger/package-lock.json +++ b/packages/input-output-logger/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/input-output-logger", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/input-output-logger/package.json b/packages/input-output-logger/package.json index 7a11ba409..6bf63b2f9 100644 --- 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 index 1cb72aa38..2b1051b16 100644 --- 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 index b51355f37..061a312ba 100644 --- a/packages/secrets-manager/package-lock.json +++ b/packages/secrets-manager/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/secrets-manager", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/secrets-manager/package.json b/packages/secrets-manager/package.json index 943a533d8..066af14c6 100644 --- 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 index ee6d8e01c..164b91d4c 100644 --- a/packages/ssm/package-lock.json +++ b/packages/ssm/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/ssm", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/ssm/package.json b/packages/ssm/package.json index fcec76135..54a345a24 100644 --- 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 index 8cc1eadd0..eb04db597 100644 --- a/packages/validator/package-lock.json +++ b/packages/validator/package-lock.json @@ -1,6 +1,6 @@ { "name": "@middy/validator", - "version": "1.0.0-alpha.34", + "version": "1.0.0-alpha.35", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/validator/package.json b/packages/validator/package.json index 79344063e..6655ec142 100644 --- 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 index 19c1f31a7..8f5dedd76 100644 --- 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"