AWS lambda documentation change
Summary
Added sections on CommonJS vs ES Modules, Node.js initialization patterns, and new handler types (synchronous and response streaming). Updated handler signature examples and reorganized content.
Security assessment
Changes focus on general functionality updates (module systems, initialization patterns, handler types) without addressing vulnerabilities or security mechanisms. No evidence of patching exploits or documenting security controls.
Diff
diff --git a/lambda/latest/dg/nodejs-handler.md b/lambda/latest/dg/nodejs-handler.md index bdedc7d91..bd66fd543 100644 --- a//lambda/latest/dg/nodejs-handler.md +++ b//lambda/latest/dg/nodejs-handler.md @@ -5 +5 @@ -Set up your projectExample functionHandler naming conventionsInput event objectValid handler patternsUsing the SDK for JavaScriptAccessing environment variablesUsing global stateBest practices +Set up your projectExample functionCommonJS and ES ModulesNode.js initializationHandler naming conventionsInput event objectValid handler patternsUsing the SDK for JavaScriptAccessing environment variablesUsing global stateBest practices @@ -18,0 +19,4 @@ This page describes how to work with Lambda function handlers in Node.js, includ + * CommonJS and ES Modules + + * Node.js initialization + @@ -47 +51 @@ This command initializes your project and generates a `package.json` file that m -Your function code lives in a `.js` or `.mjs` JavaScript file. In the following example, we name this file `index.mjs` because it uses an ES module handler. Lambda supports both ES module and CommonJS handlers. For more information, see [Designating a function handler as an ES module](./lambda-nodejs.html#designate-es-module). +Your function code lives in a `.js` or `.mjs` JavaScript file. In the following example, we name this file `index.mjs` because it uses an ES module handler. Lambda supports both ES module and CommonJS handlers. For more information, see CommonJS and ES Modules. @@ -62,4 +65,0 @@ The following example Lambda function code takes in information about an order, -###### Note - -This example uses an ES module handler. Lambda supports both ES module and CommonJS handlers. For more information, see [Designating a function handler as an ES module](./lambda-nodejs.html#designate-es-module). - @@ -142,0 +143,57 @@ For this function to work properly, its [ execution role](./lambda-intro-executi +## CommonJS and ES Modules + +Node.js supports two module systems: CommonJS and ECMAScript modules (ES modules). Lambda recommends using ES modules as it supports top-level await, which enables asynchronous tasks to be completed during execution environment initialization. + +Node.js treats files with a `.cjs` file name extension as CommonJS modules while a `.mjs` extension denotes ES modules. By default, Node.js treats files with the `.js` file name extension as CommonJS modules. You can configure Node.js to treat `.js` files as ES modules by specifying the `type` as `module` in the function's `package.json` file. You can configure Node.js in Lambda to detect automatically whether a `.js` file should be treated as CommonJS or as an ES module by adding the `—experimental-detect-module` flag to the `NODE_OPTIONS` environment variable. For more information, see [Experimental Node.js features](./lambda-nodejs.html#nodejs-experimental-features). + +The following examples show function handlers written using both ES modules and CommonJS modules. The remaining examples on this page all use ES modules. + +ES module example + + +###### Example – ES module handler + + + const url = "https://aws.amazon.com/"; + + export const handler = async(event) => { + try { + const res = await fetch(url); + console.info("status", res.status); + return res.status; + } + catch (e) { + console.error(e); + return 500; + } + }; + +CommonJS module example + + +###### Example – CommonJS module handler + + + const https = require("https"); + let url = "https://aws.amazon.com/"; + + exports.handler = async function (event) { + let statusCode; + await new Promise(function (resolve, reject) { + https.get(url, (res) => { + statusCode = res.statusCode; + resolve(statusCode); + }).on("error", (e) => { + reject(Error(e)); + }); + }); + console.log(statusCode); + return statusCode; + }; + +## Node.js initialization + +Node.js uses a non-blocking I/O model that supports efficient asynchronous operations using an event loop. For example, if Node.js makes a network call, the function continues to process other operations without blocking on a network response. When the network response is received, it is placed into the callback queue. Tasks from the queue are processed when the current task completes. + +Lambda recommends using top-level await so that asynchronous tasks initiated during execution environment initialization are completed during initialization. Asynchronous tasks that are not completed during initialization will typically run during the first function invoke. This can cause unexpected behavior or errors. For example, your function initialization may make a network call to fetch a parameter from AWS Parameter Store. If this task is not completed during initialization, the value may be null during an invocation. There can also be a delay between initialization and invoke which can trigger errors in time-sensitive operations. In particular, AWS service calls can rely on time-sensitive request signatures, resulting in service call failures if the call is not completed during the initialization phase. Completing tasks during initialization typically improves cold-start performance, and first invoke performance when using Provisioned Concurrency. For more information, see our blog post [Using Node.js ES modules and top-level await in AWS Lambda](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda). + @@ -193 +250 @@ We recommend that you use [async/await](https://docs.aws.amazon.com/sdk-for-java -### Using async/await (recommended) +### async function handlers (recommended) @@ -206 +262,0 @@ Here are the valid signatures for the async/await pattern: - * export const handler = async (event) => { }; @@ -208 +264 @@ Here are the valid signatures for the async/await pattern: - * export const handler = async (event, context) => { }; + export const handler = async (event) => { }; @@ -210,0 +267 @@ Here are the valid signatures for the async/await pattern: + export const handler = async (event, context) => { }; @@ -211,0 +269 @@ Here are the valid signatures for the async/await pattern: +### Synchronous function handlers @@ -213 +271 @@ Here are the valid signatures for the async/await pattern: -###### Note +Where your function does not perform any asynchronous tasks, you can use a synchronous function handler, using one of the following function signatures: @@ -215 +272,0 @@ Here are the valid signatures for the async/await pattern: -Use a local integrated development environment (IDE) or text editor to write your TypeScript function code. You can’t create TypeScript code on the Lambda console. @@ -217 +274,19 @@ Use a local integrated development environment (IDE) or text editor to write you -### Using callbacks + export const handler = (event) => { }; + + + export const handler = (event, context) => { }; + +### Response streaming function handlers + +Lambda supports response streaming with Node.js. Response streaming function handlers use the `awslambda.streamifyResponse()` decorator and take 3 parameters: `event`, `responseStream`, and `context`. The function signature is: + + + export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => { }); + +For more information, see [Response streaming for Lambda functions](./configuration-response-streaming.html). + +### Callback-based function handlers + +###### Note + +Callback-based function handlers are only supported up to Node.js 22. Starting from Node.js 24, asynchronous tasks should be implemented using async function handlers. @@ -219 +294 @@ Use a local integrated development environment (IDE) or text editor to write you -Callback handlers must use the event, context, and callback arguments. Example: +Callback-based function handlers must use the event, context, and callback arguments. Example: