In this section, we'll look at objects that get passed to the handler on initialization. First off is the event object. This is a really useful piece of data and is necessary if you want to access the external inputs that the function was called with. This data is input to the handler function on initialization and provides information about the originating request. Additionally, the context object provides extra information about this, as well as methods that are supplied by AWS, that can help introspect the environment and other things.

If you're invoking a function through the API or SDKs, you can include some arbitrary JSON data along with it. This data is accessible during runtime through the event object. As an example, to invoke a Lambda function and include some data using the CLI, you could run something like this:

aws lambda invoke 
    --invocation-type RequestResponse 
    --function-name HelloWorldFunction 
    --payload '{"hello":"world", "alice":"bob"}'

If another service invokes the lambda, that service will often include useful information in the event. For example, if you have an API Gateway backed by a Lambda function, when a request to an API Gateway method triggers the function, it will include a message event. In that event, you will find things such as the path of the method request, any special headers proxied to the Lambda, the HTTP method used, and the parameters from the path or query string. These pieces of data are useful when determining how to handle the request.

Each service will send an event object with a different format, so it's worth checking the Lambda documentation to see what you can expect: https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html.

The next thing to mention is the context object. This object provides some properties and methods that you can use to introspect the running environment. The object itself will be in a different format, depending on the runtime you choose, so it pays to check the documentation to see what's available. There are a couple of things to talk about here.

The first is the getRemainingTimeInMillis() method, which returns the number of milliseconds that remain for execution before hitting the preconfigured maximum timeout value. The reason that this is useful is that you can use this information to make a decision about whether you have time to do more work, or if you should recurse and spawn another function. It's also useful for when the client or consumer of the function is running something time-sensitive, such as an HTTP GET response or updating a view on a frontend web application.

The next useful thing in the context object applies only to Node.js. JavaScript uses a combination of a last-in-first-out (LIFO) call stack, a first-in-first-out (FIFO) task queue, and an event loop to implement its concurrency model. It is possible to get into a situation where a Lambda function can terminate before all the background processes or callbacks are complete. If you think that could be a possibility, you could make some adjustments to your code (such as adding an await to function calls). It is also possible that a task in the queue or the stack could be holding up the hander's callback from being run.

In this case, the function is likely to reach its timeout period and terminate with an error. To avoid that, you can instruct Lambda to terminate the function after the callback is called with a nifty property called callbackWaitsForEmptyEventLoop. Set this to false if you wish, but note that any tasks remaining in the event loop will be processed on the subsequent invocation of the same Lambda instance. The details of this get complex quite quickly, so we will revisit Lambda instance reuse in Chapter 6, Going Deeper with Lambda.