lambda-handlers

Lambda Handler Patterns

Overview

AWS Lambda functions require specific patterns to handle cold starts, memory constraints, timeouts, and concurrent executions efficiently.

Dependencies

Use Middy v7 and Node.js 22 runtime. Middy v7 has breaking changes from v5 (see upgrade guide).

pnpm add @middy/core@^7 @middy/http-json-body-parser@^7 @middy/http-error-handler@^7 @middy/input-output-logger@^7 @middy/http-cors@^7
pnpm add @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
pnpm add -D @types/aws-lambda esbuild

Base Handler Structure

Simple Handler

// src/functions/get-property/handler.ts

import type { APIGatewayProxyHandler, APIGatewayProxyResult } from "aws-lambda";
import { logger } from "@/shared/logger";

export const handler: APIGatewayProxyHandler = async (event, context) => {
  // Disable waiting for event loop to empty (faster cold starts)
  context.callbackWaitsForEmptyEventLoop = false;

  const propertyId = event.pathParameters?.propertyId;

  if (!propertyId) {
    return {
      statusCode: 400,
      body: JSON.stringify({ message: "Property ID is required" }),
    };
  }

  try {
    const property = await propertyService.findById(propertyId);

    if (!property) {
      return {
        statusCode: 404,
        body: JSON.stringify({ message: "Property not found" }),
      };
    }

    return {
      statusCode: 200,
      body: JSON.stringify(property),
    };
  } catch (error) {
    logger.error({ err: error, propertyId }, "Failed to get property");
    return {
      statusCode: 500,
      body: JSON.stringify({ message: "Internal server error" }),
    };
  }
};

Middy Middleware Pattern (Recommended)

Middleware Stack Setup

// src/shared/middleware/index.ts

import middy from "@middy/core";
import httpJsonBodyParser from "@middy/http-json-body-parser";
import httpErrorHandler from "@middy/http-error-handler";
import inputOutputLogger from "@middy/input-output-logger";
import httpCors from "@middy/http-cors";
import { injectLambdaContext } from "@aws-lambda-powertools/logger/middleware";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import { logger } from "@/shared/logger";
import { tracer } from "@/shared/tracer";
import { correlationIdMiddleware } from "./correlation-id";
import { validationMiddleware } from "./validation";

export function createHandler<TEvent, TResult>(
  handler: (event: TEvent, context: Context) => Promise<TResult>
) {
  return middy(handler)
    .use(injectLambdaContext(logger, { clearState: true }))
    .use(captureLambdaHandler(tracer))
    .use(correlationIdMiddleware())
    .use(httpCors({ origin: "*", credentials: true })) // Real estate web app: allow frontend origin
    .use(inputOutputLogger({
      logger: (request) => logger.debug(request),
      awsContext: true,
    }))
    .use(httpJsonBodyParser())
    .use(httpErrorHandler({ logger: (error) => logger.error({ err: error }) }));
}