Understanding DynamoDB Stream Event Types in TypeScript

When working with AWS DynamoDB and handling stream events in a serverless architecture using AWS Lambda, it's crucial to understand the types and structures of DynamoDB stream events, especially when working with TypeScript. The use of appropriate types ensures type safety, avoids runtime errors, and improves code readability. This article delves into the structure and handling of DynamoDB stream events in TypeScript.

DynamoDB Stream Basics

DynamoDB Streams capture modifications to items in a table and perform actions in response, like archiving records or updating search indices. When an item in a table is inserted, updated, or deleted, the stream captures details of the modification and triggers a Lambda function that can process these changes.

Understanding DynamoDB Stream Event Structure

1. Event Source: aws:dynamodb
2. Event Version: Typically 1.1 for most applications.
3. Records: A list of records, where each record represents a change to an item in the table.

Each record comprises:

• eventID: A unique identifier for the event.
• eventName: The type of operation that caused the event. Possible values are INSERT, MODIFY, and REMOVE.
• eventVersion: The version of the event format.
• eventSource: The source of the event; should be aws:dynamodb.
• awsRegion: The AWS region where the source DynamoDB table resides.
• dynamodb: Contains several subfields including:
  • Keys: The primary key attributes of the item that was modified.
  • NewImage: The state of the item after the modification.
  • OldImage: The state of the item before the modification, if available.
  • SequenceNumber: A globally unique identifier for the event.
  • SizeBytes: The size of the stream record.
• userIdentity: Information about the user that made the changes, if applicable.

TypeScript Type for DynamoDB Stream Event

AWS SDKs provide TypeScript types to facilitate handling DynamoDB events seamlessly. However, we often handle these events using AWS Lambda, so the @aws-lambda-types/scripts package provided by DefinitelyTyped is commonly used.

Here's how you can define the type for a DynamoDB stream event in TypeScript:

1import { DynamoDBStreamEvent, DynamoDBRecord } from 'aws-lambda';
2
3export const handler = async (event: DynamoDBStreamEvent): Promise<void> => {
4  event.Records.forEach((record: DynamoDBRecord) => {
5    console.log('Event ID:', record.eventID);
6    console.log('Event Name:', record.eventName);
7
8    if (record.dynamodb) {
9      if (record.dynamodb.Keys) {
10        console.log('Primary Key:', JSON.stringify(record.dynamodb.Keys));
11      }
12      if (record.dynamodb.NewImage) {
13        console.log('New Image:', JSON.stringify(record.dynamodb.NewImage));
14      }
15      if (record.dynamodb.OldImage) {
16        console.log('Old Image:', JSON.stringify(record.dynamodb.OldImage));
17      }
18    }
19  });
20};

Key Concepts

1. Type Safety: Using the DynamoDBStreamEvent and DynamoDBRecord types, ensures that the code handles the event object correctly, minimizing risks of runtime type errors.
2. Event Handling: Typically, each DynamoDBRecord in event.Records is processed to apply business logic, like updating other services or data stores with changes.
3. Dealing with Images: The NewImage and OldImage fields use DynamoDB's internal data representation, which includes values as S for strings, N for numbers, etc. Proper parsing and conversion are needed for application use.

Summary Table

Conclusion

Leveraging TypeScript with DynamoDB Streams allows for robust and type-safe handling of data modification events. Properly typed handlers not only prevent potential errors but also enrich the development experience by providing compile-time checks and autocompletion features. By using the @types/aws-lambda package, developers can easily set up handlers that conform to the expected structure of DynamoDB stream events and focus on delivering business logic efficiently.