AWS DynamoDB CRUD Operations in Node.js with the AWS SDK v3

Quick Tip

Wrap the low-level DynamoDB client in a DynamoDBDocumentClient so you pass plain JavaScript objects in and get plain objects back, then guard your writes with ConditionExpression and read by key with QueryCommand.

The Problem

The Problem

The low-level DynamoDB API doesn’t speak JavaScript. Every value has to be wrapped in a typed attribute map, so a simple { id: "42", count: 3 } turns into { id: { S: "42" }, count: { N: "3" } } on the way in, and you have to unwrap all of it on the way out. Write that marshalling by hand across a codebase and it becomes a steady drip of ValidationException errors and off-by-one type bugs.

Why raw attribute maps hurt

The attribute-map format leaks into every call site. You can’t just hand DynamoDB the object your app already has, you first translate it, then translate the response back, and you repeat that boilerplate for put, get, update, and query. It’s easy to send a number as a string or forget a nested map, and DynamoDB rejects the whole request rather than coercing anything for you.

The real-world impact

That friction shows up as slow feature work and brittle data access. New team members trip over the { S: ... } wrappers, updates accidentally overwrite fields they never meant to touch, and someone reaches for Scan because it “just works,” quietly reading the entire table on every call. The result is code that’s harder to review and a bill that grows faster than the data.

The Solution

The Fix

Use the AWS SDK v3 DynamoDBDocumentClient. It wraps the base DynamoDBClient and handles marshalling in both directions, so your CRUD code deals in plain objects. Pair it with a single table, address items by their partition and sort keys, use UpdateCommand to change only the fields you name, and add a ConditionExpression when a write must not clobber existing data.

TL;DR

• Wrap DynamoDBClient in DynamoDBDocumentClient so you never touch raw attribute maps.
• Use PutCommand, GetCommand, UpdateCommand, and DeleteCommand for CRUD, with ConditionExpression to keep writes safe.
• Read with QueryCommand on the partition key instead of scanning the whole table.

Script Implementation

Setup and the DocumentClient

Create the base client once, wrap it in a DynamoDBDocumentClient, and turn on the marshalling options that smooth over DynamoDB’s quirks. Reuse this single instance across your app so connections get pooled.

1
// dynamo.ts - CRUD helpers for a single DynamoDB table with the AWS SDK v3.
2
import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
3
import {
4
  DynamoDBDocumentClient,
5
  PutCommand,
6
  GetCommand,
7
  UpdateCommand,
8
  DeleteCommand,
9
  QueryCommand,
10
} from '@aws-sdk/lib-dynamodb';
11

12
const TABLE_NAME = process.env.TABLE_NAME ?? 'AppTable';
13

14
// One low-level client for the process; region comes from the environment.
15
const baseClient = new DynamoDBClient({});
16

17
// The DocumentClient marshals plain JS objects to/from attribute maps.
18
export const ddb = DynamoDBDocumentClient.from(baseClient, {
19
  marshallOptions: {
20
    // Drop undefined fields instead of erroring on them.
21
    removeUndefinedValues: true,
22
    // Store empty strings and sets as-is rather than converting to null.
23
    convertEmptyValues: false,
24
  },
25
});
26

27
// A tiny item shape for the examples: single-table keys plus data.
28
export interface User {
29
  pk: string; // partition key, e.g. "USER#42"
30
  sk: string; // sort key, e.g. "PROFILE"
31
  name: string;
32
  email: string;
33
  loginCount?: number;
34
}

Create and read: put and get

PutCommand writes a whole item, overwriting any existing item with the same key. GetCommand fetches one item by its full primary key and returns a plain object, or undefined when nothing matches.

1
// Create or overwrite an item. Pass the object as-is, no attribute maps.
2
export async function putUser(user: User): Promise<void> {
3
  await ddb.send(
4
    new PutCommand({
5
      TableName: TABLE_NAME,
6
      Item: user,
7
    }),
8
  );
9
}
10

11
// Fetch a single item by its partition + sort key.
12
export async function getUser(
13
  pk: string,
14
  sk: string,
15
): Promise<User | undefined> {
16
  const {Item} = await ddb.send(
17
    new GetCommand({
18
      TableName: TABLE_NAME,
19
      Key: {pk, sk},
20
    }),
21
  );
22
  // Item is already a plain object, cast it to the known shape.
23
  return Item as User | undefined;
24
}

Update and delete safely

UpdateCommand changes only the fields you name in the UpdateExpression, so you never overwrite the rest of the item. The ConditionExpression makes the update fail loudly if the item doesn’t already exist, which stops accidental “upserts.” DeleteCommand removes an item by key.

1
// Update named fields only, and require that the item already exists.
2
export async function bumpLoginCount(pk: string, sk: string): Promise<User> {
3
  const {Attributes} = await ddb.send(
4
    new UpdateCommand({
5
      TableName: TABLE_NAME,
6
      Key: {pk, sk},
7
      // ADD creates loginCount at 1 if missing, otherwise increments it.
8
      UpdateExpression: 'ADD loginCount :one',
9
      ConditionExpression: 'attribute_exists(pk)',
10
      ExpressionAttributeValues: {':one': 1},
11
      ReturnValues: 'ALL_NEW',
12
    }),
13
  );
14
  return Attributes as User;
15
}
16

17
// Delete an item by key. Idempotent: deleting a missing key is a no-op.
18
export async function deleteUser(pk: string, sk: string): Promise<void> {
19
  await ddb.send(
20
    new DeleteCommand({
21
      TableName: TABLE_NAME,
22
      Key: {pk, sk},
23
    }),
24
  );
25
}

Query by key instead of scanning

QueryCommand reads every item that shares a partition key, optionally narrowed by the sort key. This is the read you want almost every time, it touches only the matching items instead of the whole table the way Scan does.

1
// Fetch every item under one partition key, e.g. all records for a user.
2
export async function queryByUser(pk: string): Promise<User[]> {
3
  const items: User[] = [];
4
  let ExclusiveStartKey: Record<string, unknown> | undefined;
5

6
  // Loop to follow pagination until DynamoDB stops returning a cursor.
7
  do {
8
    const page = await ddb.send(
9
      new QueryCommand({
10
        TableName: TABLE_NAME,
11
        KeyConditionExpression: 'pk = :pk',
12
        ExpressionAttributeValues: {':pk': pk},
13
        ExclusiveStartKey,
14
      }),
15
    );
16
    items.push(...((page.Items ?? []) as User[]));
17
    ExclusiveStartKey = page.LastEvaluatedKey;
18
  } while (ExclusiveStartKey);
19

20
  return items;
21
}

Entry point with error handling

Tie the helpers together in a small demo and catch the one error you actually expect: a failed ConditionExpression. DynamoDB reports it as a ConditionalCheckFailedException, which you handle rather than crash on.

1
import {ConditionalCheckFailedException} from '@aws-sdk/client-dynamodb';
2

3
async function main(): Promise<void> {
4
  const key = {pk: 'USER#42', sk: 'PROFILE'};
5

6
  await putUser({...key, name: 'Ada', email: '[email protected]'});
7
  console.log('created:', await getUser(key.pk, key.sk));
8

9
  try {
10
    const updated = await bumpLoginCount(key.pk, key.sk);
11
    console.log('login count is now', updated.loginCount);
12
  } catch (err) {
13
    if (err instanceof ConditionalCheckFailedException) {
14
      console.error('update skipped: that user does not exist yet');
15
    } else {
16
      throw err; // Anything else is unexpected, let it surface.
17
    }
18
  }
19

20
  console.log('all records:', await queryByUser(key.pk));
21
  await deleteUser(key.pk, key.sk);
22
}
23

24
main().catch((err) => {
25
  console.error(err);
26
  process.exit(1);
27
});

Usage and Benefits

Why This Helps

The DocumentClient deletes an entire category of bugs by letting you work in plain objects, and the CRUD helpers give every call site the same safe pattern: named updates, conditional writes, and key-based reads. You stop hand-writing attribute maps, stop accidentally overwriting fields, and stop reaching for Scan when a Query is right there.

Real invocations

1
# Install the SDK v3 packages.
2
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
3

4
# Set the table and region, then run the compiled script.
5
export AWS_REGION=us-east-1
6
export TABLE_NAME=AppTable
7
node dynamo.js
8

9
# Or run the TypeScript directly during development.
10
npx tsx dynamo.ts

Tuning for single-table design

The pk/sk pair is the heart of single-table design: you overload one table with many item types by encoding the type into the key. A user profile might use pk = "USER#42", sk = "PROFILE", while their orders use the same pk with sk = "ORDER#1001". One QueryCommand on USER#42 then pulls the profile and every order in a single call.

1
// Same partition key, different sort keys, one query returns them all.
2
await putUser({
3
  pk: 'USER#42',
4
  sk: 'PROFILE',
5
  name: 'Ada',
6
  email: '[email protected]',
7
});
8
await putUser({pk: 'USER#42', sk: 'ORDER#1001', name: 'order', email: '-'});
9

10
// begins_with narrows a query to just the orders under this user.
11
const orders = await ddb.send(
12
  new QueryCommand({
13
    TableName: TABLE_NAME,
14
    KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',
15
    ExpressionAttributeValues: {':pk': 'USER#42', ':prefix': 'ORDER#'},
16
  }),
17
);

Comparison

How the SDK v3 DocumentClient stacks up against the other common ways to talk to DynamoDB from Node.js.

The low-level client is worth dropping to only when you need something the DocumentClient doesn’t expose. For everyday CRUD, the document client’s automatic marshalling is the reason it exists.

Frequently Asked Questions

References

• AWS SDK v3: @aws-sdk/lib-dynamodb (DocumentClient)
• AWS SDK v3: @aws-sdk/client-dynamodb
• DynamoDB Developer Guide: Query operations
• DynamoDB Developer Guide: Condition expressions
• DynamoDB Developer Guide: Single-table design
• AWS SDK for JavaScript v3 Developer Guide