@aws-sdk/lib-dynamodb

What is @aws-sdk/lib-dynamodb?

The @aws-sdk/lib-dynamodb package is a library that provides a simpler interface for interacting with Amazon DynamoDB from JavaScript applications. It is part of the AWS SDK for JavaScript (v3) and offers an abstraction over the lower-level DynamoDB client, making it easier to work with DynamoDB using JavaScript objects and syntax.

What are @aws-sdk/lib-dynamodb's main functionalities?

Performing CRUD Operations

This feature allows you to create, read, update, and delete items in a DynamoDB table. The code sample demonstrates how to insert an item into a DynamoDB table using the PutCommand.

{"PutCommand": "const { DynamoDBDocumentClient, PutCommand } = require('@aws-sdk/lib-dynamodb'); const client = DynamoDBDocumentClient.from(new DynamoDBClient({})); const putCommand = new PutCommand({ TableName: 'MyTable', Item: { id: '1', content: 'example' } }); client.send(putCommand);"}

Querying and Scanning Tables

This feature allows you to query items using a key condition expression or scan the entire table. The code sample shows how to query items from a DynamoDB table where the 'id' attribute matches a specific value.

{"QueryCommand": "const { DynamoDBDocumentClient, QueryCommand } = require('@aws-sdk/lib-dynamodb'); const client = DynamoDBDocumentClient.from(new DynamoDBClient({})); const queryCommand = new QueryCommand({ TableName: 'MyTable', KeyConditionExpression: 'id = :id', ExpressionAttributeValues: { ':id': '1' } }); client.send(queryCommand);"}

Batch Operations

This feature allows you to perform batch operations, such as batch writes (put and delete), on multiple items across one or more tables. The code sample demonstrates how to perform a batch write operation to put and delete items in a DynamoDB table.

{"BatchWriteCommand": "const { DynamoDBDocumentClient, BatchWriteCommand } = require('@aws-sdk/lib-dynamodb'); const client = DynamoDBDocumentClient.from(new DynamoDBClient({})); const batchWriteCommand = new BatchWriteCommand({ RequestItems: { 'MyTable': [ { PutRequest: { Item: { id: '2', content: 'example2' } } }, { DeleteRequest: { Key: { id: '3' } } } ] } }); client.send(batchWriteCommand);"}

Transaction Support

This feature allows you to perform multiple put, update, and delete operations across multiple tables atomically. The code sample shows how to use the TransactWriteItemsCommand to perform atomic transactions in DynamoDB.

{"TransactWriteItemsCommand": "const { DynamoDBDocumentClient, TransactWriteItemsCommand } = require('@aws-sdk/lib-dynamodb'); const client = DynamoDBDocumentClient.from(new DynamoDBClient({})); const transactWriteItemsCommand = new TransactWriteItemsCommand({ TransactItems: [ { Put: { TableName: 'MyTable', Item: { id: '4', content: 'example4' } } }, { Delete: { TableName: 'MyTable', Key: { id: '5' } } } ] }); client.send(transactWriteItemsCommand);"}

Other packages similar to @aws-sdk/lib-dynamodb

dynamoose

Dynamoose is a modeling tool for Amazon DynamoDB that provides a higher-level abstraction than @aws-sdk/lib-dynamodb. It offers features like schema definition, validation, and more complex query capabilities. It is designed to be similar to Mongoose, which is a modeling tool for MongoDB.

dynamo-types

Dynamo-types is a TypeScript library that provides a strong-typed way to define models for DynamoDB tables. It offers decorators to define table schemas and is built on top of the AWS SDK. It is more TypeScript-oriented compared to @aws-sdk/lib-dynamodb, which is more JavaScript-focused.

README

@aws-sdk/lib-dynamodb

Overview

The document client simplifies working with items in Amazon DynamoDB by abstracting away the notion of attribute values. This abstraction annotates native JavaScript types supplied as input parameters, as well as converts annotated response data to native JavaScript types.

Marshalling Input and Unmarshalling Response Data

The document client affords developers the use of native JavaScript types instead of AttributeValues to simplify the JavaScript development experience with Amazon DynamoDB. JavaScript objects passed in as parameters are marshalled into AttributeValue shapes required by Amazon DynamoDB. Responses from DynamoDB are unmarshalled into plain JavaScript objects by the DocumentClient. The DocumentClient does not accept AttributeValues in favor of native JavaScript types.

JavaScript Type	DynamoDB AttributeValue
String	S
Number / BigInt	N
Boolean	BOOL
null	NULL
Array	L
Object	M
Set<Uint8Array, Blob, ...>	BS
Set<Number, BigInt>	NS
Set<String>	SS
Uint8Array, Buffer, File, Blob...	B

Example

Here is an example list which is sent to DynamoDB client in an operation:

{ "L": [{ "NULL": true }, { "BOOL": false }, { "N": 1 }, { "S": "two" }] }

The DynamoDB document client abstracts the attribute values as follows in both input and output:

[null, false, 1, "two"]

Usage

To create document client you need to create DynamoDB client first as follows:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); // CommonJS import

// Bare-bones DynamoDB Client
const client = new DynamoDBClient({});

import { DynamoDB } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDB } = require("@aws-sdk/client-dynamodb"); // CommonJS import

// Full DynamoDB Client
const client = new DynamoDB({});

The bare-bones clients are more modular. They reduce bundle size and improve loading performance over full clients as explained in blog post on modular packages in AWS SDK for JavaScript.

Constructor

Once DynamoDB client is created, you can either create the bare-bones document client or full document client as follows:

import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocumentClient } = require("@aws-sdk/lib-dynamodb"); // CommonJS import

// Bare-bones document client
const ddbDocClient = DynamoDBDocumentClient.from(client); // client is DynamoDB client

import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocument } = require("@aws-sdk/lib-dynamodb"); // CommonJS import

// Full document client
const ddbDocClient = DynamoDBDocument.from(client); // client is DynamoDB client

Configuration

The configuration for marshalling and unmarshalling can be sent as an optional second parameter during creation of document client as follows:

const marshallOptions = {
  // Whether to automatically convert empty strings, blobs, and sets to `null`.
  convertEmptyValues: false; // false, by default.
  // Whether to remove undefined values while marshalling.
  removeUndefinedValues: false; // false, by default.
  // Whether to convert typeof object to map attribute.
  convertClassInstanceToMap: false; // false, by default.
};

const unmarshallOptions = {
  // Whether to return numbers as a string instead of converting them to native JavaScript numbers.
  wrapNumbers: false; // false, by default.
};

const translateConfig = { marshallOptions, unmarshallOptions };

const client = new DynamoDBClient({});
const ddbDocClient = DynamoDBDocument.from(client, translateConfig);

Calling operations

You can call the document client operations using command objects on bare-bones client as follows:

import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

// ... DynamoDB client creation

const ddbDocClient = DynamoDBDocumentClient.from(client);
// Call using bare-bones client and Command object.
await ddbDocClient.send(
  new PutCommand({
    TableName,
    Item: {
      id: "1",
      content: "content from DynamoDBDocumentClient",
    },
  })
);

You can also call operations on full client as follows:

import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

// ... DynamoDB client creation

const ddbDocClient = DynamoDBDocument.from(client);
// Call using full client.
await ddbDocClient.put({
  TableName,
  Item: {
    id: "2",
    content: "content from DynamoDBDocument",
  },
});

Destroying document client

The destroy() call on document client is a no-op as document client does not create a new DynamoDB client. You need to call destroy() on DynamoDB client to clean resources used by it as shown below.

const client = new DynamoDBClient({});
const ddbDocClient = DynamoDBDocumentClient.from(client);

// Perform operations on document client.

ddbDocClient.destroy(); // no-op
client.destroy(); // destroys DynamoDBClient

Changelog

3.10.0 (2021-03-26)

Bug Fixes

• clients: generate jest.config.js (#2172) (95b0e19)
• lib-storage: fix fs error on browsers when using lib-storage upload (#2165) (5d9bc5f)

Features

• credential-provider-ini: call fromTokenFile in assumeRole chaining (#2178) (fb95408)
• credential-provider-web-identity: add fromTokenFile credentials provider (#2177) (88cc65d)
• use ts-jest for running jest tests (#2088) (456002c)