This post was originally published on my blog on 10th August 2023
If you’ve ever tried building a project with DynamoDB and used the AWS SDK with TypeScript to read and write data to the database, you’ll probably be familiar with the issues of the SDK not typing the data you retrieve from the database.
This issue makes sense because the SDK has no way of knowing what attributes you have on every item in your database before you’ve retrieved them but this doesn’t make the issue any less annoying from a developer's perspective.
But, don’t worry in this tutorial, I’ll give you a solution so you can keep the power of the SDK and have accurate types from TypeScript for you to use in your application so let’s get into it.
The Issue
Before we jump into the solution let’s take a quick look at the problem, below is some example code using the QueryCommand
from the AWS SDK to retrieve all items in the database that match the given pk
and start with the same sk
value.
const { Items } = await dbClient.send(
new QueryCommand({
TableName: 'YOUR_TABLE_NAME',
ExpressionAttributeValues: {
':p': pk,
':s': sk,
},
KeyConditionExpression: 'pk = :p and begins_with(sk, :s)',
})
);
The issue with this code is the TypeScript type given to Items
will be Record<string, any>[] | undefined
which is far from helpful. If we wanted to access the properties on the items returned from our database, TypeScript would throw an error as it has no idea what is present on the data and what isn’t so let’s fix that so we can access the actual data we retrieve with the correct types.
The Solution
To resolve the issue with the types not being applied to the data being returned, we first need to do some digging into the SDK package itself. If we dig into the QueryCommand
we used above, we can actually see the return type being used is the one below.
export declare type QueryCommandOutput = Omit<__QueryCommandOutput, "Items" | "LastEvaluatedKey"> & {
Items?: Record<string, NativeAttributeValue>[];
LastEvaluatedKey?: Record<string, NativeAttributeValue>;
};
This is where we can see the not-very helpful Record<string, NativeAttributeValue>[] | undefined
is being returned to us. But, what if we could override that with our own types?
What we’re going to do is take the QueryCommandOutput
type and remove the built-in type for Items
and instead give it our own type that matches the data we’re retrieving from the database. We can do this with the below code.
import { QueryCommandOutput } from '@aws-sdk/lib-dynamodb';
type Item = {
prop1: string;
}
const { Items } = (await dbClient.send(
new QueryCommand({
TableName: 'YOUR_TABLE_NAME',
ExpressionAttributeValues: {
':p': pk,
':s': sk,
},
KeyConditionExpression: 'pk = :p and begins_with(sk, :s)',
})
)) as Omit<QueryCommandOutput, 'Items'> & {
Items?: Item[];
};
As mentioned above, we take the QueryCommandOutput
type and use it with the Omit
feature from TypeScript to remove the Items
type. We then extend that type with our own type for Items
which will be used for the Items
property returned from the SDK.
So, in the case of our example above we took our Items
property from having a type of Record<string, NativeAttributeValue>[] | undefined
to having a type of Item[] | undefined
which is a lot nicer to use and work with!
Making It Reusable With Generics
But, let’s not stop there, we can take this one step further and make our solution easier to reuse across our entire project by pairing it with generics and creating a new standalone type like the one below.
export type IQueryCommandOutput<T> = Omit<QueryCommandOutput, 'Items'> & {
Items?: T;
};
We can now use this type with any QueryCommand
in our codebase and provide it with a type to substitute with the generic T
so we can have nicely typed data for all of our queries. Here is our example updated to use this new abstraction.
// types.ts
import { QueryCommandOutput } from '@aws-sdk/lib-dynamodb';
export type Item = {
prop1: string;
}
export type IQueryCommandOutput<T> = Omit<QueryCommandOutput, 'Items'> & {
Items?: T;
};
// query.ts
import { Item, IQueryCommandOutput } from './types';
const { Items } = (await dbClient.send(
new QueryCommand({
TableName: 'YOUR_TABLE_NAME',
ExpressionAttributeValues: {
':p': pk,
':s': sk,
},
KeyConditionExpression: 'pk = :p and begins_with(sk, :s)',
})
)) as IQueryCommandOutput<Item[]>;
Example Code Snippets
We’ve covered the QueryCommand
from the AWS SDK throughout this post but here are the snippets you’ll need for the other common commands used when interacting with a DynamoDB table via the AWS SDK.
Scan
export type IScanCommandOutput<T> = Omit<ScanCommandOutput, 'Items'> & {
Items?: T;
};
Query
export type IQueryCommandOutput<T> = Omit<QueryCommandOutput, 'Items'> & {
Items?: T;
};
Get
export type IGetCommandOutput<T> = Omit<GetCommandOutput, 'Item'> & {
Item?: T;
};
Put
export type IPutCommandOutput<T> = Omit<
PutCommandOutput,
'Attributes'
> & {
Attributes?: T;
};
Delete
export type IDeleteCommandOutput<T> = Omit<
DeleteCommandOutput,
'Attributes'
> & {
Attributes?: T;
};
Update
export type IUpdateCommandOutput<T> = Omit<
UpdateCommandOutput,
'Attributes'
> & {
Attributes?: T;
};
Considerations
While this method does work great and all of the values returned to you from the SDK will have the appropriate types you passed to the generic, something you will need to bare in mind is that you’ll need to manually maintain the TypeScript types/interfaces you use.
This is because the types can’t be created from the database items themselves so we need to manually create the types and align them with the data in the database. This of course could introduce some issues if the types aren’t kept up to date or aren’t accurate to the data being stored.
However, I do think this issue is a minor one compared to the benefits of having working types assigned to the data returned from the SDK.
Closing Thoughts
We’ve now reached the end of this post; in this tutorial, we’ve looked at how to type the data returned to us from a DynamoDB table using the AWS SDK in a TypeScript project. I hope you found this post helpful until next time.
Thank you for reading
Coner
Top comments (0)