powertools-batch

Powertools Batch Processing

Overview

@aws-lambda-powertools/batch provides a standard way to process SQS, Kinesis, and DynamoDB Streams events with automatic partial batch failure reporting. Use it instead of manually building batchItemFailures and classifying retryable errors.

Dependencies

pnpm add @aws-lambda-powertools/batch

SQS Batch Processor

// src/functions/process-listings/handler.ts

import type { SQSEvent, SQSRecord, SQSBatchResponse } from "aws-lambda";
import { BatchProcessor, EventType, processPartialResponse } from "@aws-lambda-powertools/batch";
import { logger } from "@/shared/logger";
import { listingService } from "@/services/listing.service";

const processor = new BatchProcessor(EventType.SQS);

export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
  return processPartialResponse(event, processor, async (record: SQSRecord) => {
    const message = JSON.parse(record.body);
    const { eventType, payload } = message.data;

    logger.info({ eventType, messageId: record.messageId }, "Processing event");

    const result = await listingService.handleListingPublished(payload);

    if (!result.success) {
      if (result.error.isRetryable) {
        throw new Error(result.error.message); // Will be reported as batch item failure
      }
      throw new NonRetryableError(result.error.message, result.error.code);
    }
  });
};

class NonRetryableError extends Error {
  constructor(
    message: string,
    public readonly code: string
  ) {
    super(message);
    this.name = "NonRetryableError";
  }
}

Retryable vs Non-Retryable

Powertools Batch reports failed items so SQS retries them. For non-retryable errors (e.g. validation), throw a custom error and use a failure handler to avoid retries, or let the message eventually go to the DLQ after max receives. To skip retries for non-retryable errors, throw with a specific name and handle in a custom onFailure callback (see Powertools docs) or use your existing SQS retry ladder and DLQ.