AWS Lambda function handler in Node.js
The Lambda function handler is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method. Your function runs until the handler returns a response, exits, or times out.
The following example function logs the contents of the event object and returns the location of the logs.
Note
This page shows examples of both CommonJS and ES module handlers. To learn about the difference between these two handler types, see Designating a function handler as an ES module.
When you configure a function, the value of the handler setting is
the file name and the name of the exported handler method, separated by a dot. The default in the console and for
examples in this guide is index.handler
. This indicates the handler
method that's exported
from the index.js
file.
The runtime passes arguments to the handler method. The first argument is the event
object,
which contains information from the invoker. The invoker passes this information as a JSON-formatted string when it
calls Invoke, and the runtime converts it to an object. When an AWS service invokes your function, the event
structure varies by service.
The second argument is the context object, which contains information about the invocation, function, and execution environment. In the preceding example, the function gets the name of the log stream from the context object and returns it to the invoker.
You can also use a callback argument, which is a function that you can call in non-async handlers to send a response. We recommend that you use async/await instead of callbacks. Async/await provides improved readability, error handling, and efficiency. For more information about the differences between async/await and callbacks, see Using callbacks.
Using async/await
If your code performs an asynchronous task, use the async/await pattern to make sure that the handler finishes running. Async/await is a concise and readable way to write asynchronous code in Node.js, without the need for nested callbacks or chaining promises. With async/await, you can write code that reads like synchronous code, while still being asynchronous and non-blocking.
The async
keyword marks a function as asynchronous, and the await
keyword pauses the execution of the function until a Promise
is resolved.
Note
Make sure to wait for asynchronous events to complete. If the function returns before async events are complete, the function might fail or cause unexpected behavior in your application. This can happen when a forEach
loop contains an async event. forEach
loops expect a synchronous call. For more information, see Array.prototype.forEach()
The next example uses async/await to list your Amazon Simple Storage Service buckets.
Note
Before using this example, make sure that your function's execution role has Amazon S3 read permissions.
Using callbacks
We recommend that you use async/await to declare the function handler instead of using callbacks. Async/await is a better choice for several reasons:
-
Readability: Async/await code is easier to read and understand than callback code, which can quickly become difficult to follow and result in callback hell.
-
Debugging and error handling: Debugging callback-based code can be difficult. The call stack can become hard to follow and errors can easily be swallowed. With async/await, you can use try/catch blocks to handle errors.
-
Efficiency: Callbacks often require switching between different parts of the code. Async/await can reduce the number of context switches, resulting in more efficient code.
When you use callbacks in your handler, the function continues to execute until the event loop
The callback function takes two
arguments: an Error
and a response. The response object must be compatible with
JSON.stringify
.
The following example function checks a URL and returns the status code to the invoker.
In the next example, the response from Amazon S3 is returned to the invoker as soon as it's available. The timeout running on the event loop is frozen, and it continues running the next time the function is invoked.
Note
Before using this example, make sure that your function's execution role has Amazon S3 read permissions.