Lambda Handler Patterns

Write Lambda handlers that are typed, idempotent, and init-optimized for Node.js 24 on AWS.

Recipe

Quick-reference recipe card - copy-paste ready.

import type { APIGatewayProxyHandlerV2, Context } from "aws-lambda";
 
// Init phase (cold start) - runs once per execution environment
const tableName = process.env.TABLE_NAME!;
 
export const handler: APIGatewayProxyHandlerV2 = async (event, context) => {
  context.callbackWaitsForEmptyEventLoop = false;
 
  const id = event.pathParameters?.id;
  if (!id) {
    return { statusCode: 400, body: JSON.stringify({ error: "id required" }) };
  }
 
  const item = await getItem(tableName, id);
  return {
    statusCode: item ? 200 : 404,
    body: JSON.stringify(item ?? { error: "not found" }),
  };
};
 
async function getItem(table: string, id: string) {
  return { id, table };
}

When to reach for this: Every new Lambda function before adopting framework wrappers.

Working Example

// src/handlers/orders.ts
import type {
  APIGatewayProxyEventV2,
  APIGatewayProxyResultV2,
  Context,
  SQSBatchResponse,
  SQSEvent,
} from "aws-lambda";
import { processOrder } from "../services/orders.js";
 
// ---- HTTP API handler ----
export async function httpHandler(
  event

What this demonstrates:

• callbackWaitsForEmptyEventLoop = false ends invocation when handler returns (do not wait on open DB pool timers)
• Typed APIGatewayProxyEventV2 for HTTP API
• SQS partial batch failure response for retries without reprocessing successes

Deep Dive

Handler Styles

Init vs Invoke Phase

// INIT (outside handler) - cache clients, parse env
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
const ddb = new DynamoDBClient({});
 
export const handler = async () => {
  // INVOKE (inside handler) - per-request logic only
  await ddb.send(/* ... */);
};

Lambda reuses the execution environment across invocations. Put expensive setup in module scope.

Context Fields You Actually Use

export const handler = async (_event: unknown, context: Context) => {
  console.log(JSON.stringify({
    awsRequestId: context.awsRequestId,
    functionName: context.functionName,
    remainingMs: context.getRemainingTimeInMillis(),
  }));

getRemainingTimeInMillis() guards long loops before hard timeout.

Event Source Summary

Gotchas

• New DB pool per invocation inside handler - exhausts connections. Fix: module-scope pool with low max, or RDS Proxy.
• Forgetting callbackWaitsForEmptyEventLoop = false - hangs until pool idle. Fix: set false or await pool.end() (usually wrong for reuse).
• Non-idempotent SQS handlers - duplicate charges. Fix: idempotency keys in DynamoDB.
• Throwing on 4xx validation errors - Lambda marks invocation failed; may retry. Fix: return 4xx response, do not throw.
• Large event logging - PII in CloudWatch. Fix: log ids and metadata only.
• Mixing API Gateway v1 and v2 types - compile passes, runtime field missing. Fix: match integration type in IaC.

Alternatives

FAQs

Related

• Serverless Basics - Lambda vs containers
• Cold Start Mitigation - init optimization
• @aws-sdk v3 - clients in init phase
• serverless-express / aws-lambda-fastify - framework wrappers
• Serverless Best Practices - section checklist

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.