Upgrade 2.x -> 3.x
aka "The onError Reversal Update"
Version 3.x of Middy no longer supports Node.js versions 12.x. You are highly encouraged to move to Node.js 16.x. With the Node.js version change all packages are now ECMAScript Modules along side CommonJS Modules.
Notable changes
- New WebSocket middlewares
- HTTP & WebSocket Routers!
- Better error handling
- Timeout error handling
- Errors now use
{ cause }
for better context
Core
onError
middleware stack order reversed to matchafter
[Breaking Change]- If you only use
@middy/*
middlewares no change should be required - This change has trickle down effects on middlewares with
onError
(see below for details) - If you're handling errors yourself here are some things to review:
- Attach near the end so it is triggered first (likely already done)
- Remove
return response
, this will short circuit the response and block later middleware from modifying the response
- If you only use
- lambdaHandler now passes
{signal}
fromAbortController
to allow for ending lambda early to handle timeout errors plugin
argument now supports:internal
: Allow the use ofnew Proxy()
for smarter triggering in advanced use cases.timeoutEarlyInMillis
: When before lambda timeout to trigger early exit. Default5
timeoutEarlyResponse
: Function to throw a custom error or return a pre-set value. Default() => { throw new Error('Timeout') }
- Added
.handler()
method to allow easier understanding of the execution cycle - Deprecate
applyMiddleware()
and__middlewares
[Breaking Change]
Util
getInternal
error now includescause
set to an array of Errors- Catch when
X-Ray
is applied outside of handler invocation scope normalizeHttpResponse
now takesrequest
and mutates response [Breaking Change]getCache
will return{}
instead ofundefined
when not found [Breaking Change]
Middleware
cloudwatch-metrics
No change
do-not-wait-for-empty-event-loop
No change
error-logger
No change
event-normalizer
- Add support for all missing AWS events
- Refactored for performance improvements
http-content-encoding
- [New] Applies
brotli
,gzip
, andsdeflate
compression to response body
http-content-negotiation
- Add in
defaultToFirstLanguage
to allow fallback to a safe language to use
http-cors
onError
will not modify response unless error has been handled- Small refactor for performance improvements
http-error-handler
- No longer returns the response to short circuit the middleware stack to allow for easier use now that
onError
is called in reverse order.
http-event-normalizer
- Option
payloadFormatVersion
no longer needed - Will now throw error if not an http event [Breaking Change]
http-header-normalizer
- Modified so that all headers are set to lowercase when
canonical:false
[Breaking Change]
http-json-body-parser
No change
http-multipart-body-parser
- Change default charset from
binary
/latin1
toutf-8
. [Breaking Change]
http-partial-response
No change
http-response-serializer
- Renamed
default
option todefaultContentType
to improve maintainability [Breaking Change] onError
will not modify response unless error has been handled
http-router
- [New] Allow re-routing of events to different handlers
http-security-headers
onError
will not modify response unless error has been handled- Complete rewrite of options and inclusion of new HTML only headers [Breaking Change]
http-urlencode-body-parser
No change
http-urlencode-path-parser
No change
input-output-logger
- Add in new option to mask instead of omit a path.
rds-signer
- Deprecated
setToEnv
option due to possible security misuse [Breaking Change]
s3-key-normalizer
- Deprecated in favour of
event-normalizer
, v2.x compatible with v3
s3-object-response
No change
secrets-manager
- Deprecated
setToEnv
option due to possible security misuse [Breaking Change]
service-discovery
- [New] Allow easy access to discoveryInstances
sqs-json-body-parser
- Deprecated in favour of
event-normalizer
, v2.x compatible with v3
sqs-partial-batch-failure
- Complete rewrite to take advantage of https://aws.amazon.com/about-aws/whats-new/2021/11/aws-lambda-partial-batch-response-sqs-event-source/, will no longer throw an error if any message fails [Breaking Change]
ssm
- Deprecated
setToEnv
option [Breaking Change]
sts
No change
validator
- Change where errors are stored, from
request.error.details
torequest.error.cause
[Breaking Change] - Add new options
eventSchema
,contextSchema
,responseSchema
.inputSchema
andoutputSchema
become aliases.
warmup
No change
ws-json-body-parser
- [New] Parse body from WebSocket event
ws-response
- [New] Post responses to WebSocket API Gateway
ws-router
- [New] Allow re-routing of events to different handlers
Notes
If you still need setToEnv
you can do something like so:
middy(lambdaHandler)
.use(/*...*/)
.before(async (request) => {
const values = await getInternal(['NODE_ENV'], request)
process.env.NODE_ENV = values.NODE_ENV
})