feat(lib-dynamodb): add DynamoDB DocumentClient

[trivikr]

Issue

This is a cleaned up version of PR on fork: trivikr#55

Fixes: #1223

Description

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.

Usage example for bare-bones DynamoDB document client:

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

const client = new DynamoDBClient({});
const ddbDocClient = DynamoDBDocumentClient.from(client);
await ddbDocClient.send(
  new PutCommand({
    TableName,
    Item: { id: "1", content: "content from DynamoDBDocumentClient" },
  })
);

Usage example for v2 backward-compatible full DynamoDB document client:

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

const client = new DynamoDBClient({});
const ddbDoc = DynamoDBDocument.from(client);
await ddbDoc.put({
  TableName,
  Item: { id: "2", content: "content from DynamoDBDocument" },
});

Testing

get/put/delete operations

import {
  DynamoDBDocumentClient,
  DeleteCommand,
  GetCommand,
  PutCommand,
} from "../aws-sdk-js-v3/lib/lib-dynamodb";
import {
  DynamoDBClient,
  CreateTableCommand,
  DeleteTableCommand,
  waitForTableExists,
} from "../aws-sdk-js-v3/clients/client-dynamodb";

(async () => {
  const region = "us-west-2";
  const client = new DynamoDBClient({ region });

  // const TableName = "test-1763877349";
  const TableName = `test-${Math.ceil(Math.random() * 10 ** 10)}`;

  const params = {
    TableName,
    AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
    KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
    BillingMode: "PAY_PER_REQUEST",
  };

  await client.send(new CreateTableCommand(params));
  await waitForTableExists({ client, maxWaitTime: 30 }, { TableName });

  const translateConfig = {
    marshallOptions: { convertEmptyValues: true, removeUndefinedValues: true },
    unmarshallOptions: { wrapNumbers: true },
  };
  const ddbDocClient = DynamoDBDocumentClient.from(client, translateConfig);
  await ddbDocClient.send(
    new PutCommand({
      TableName,
      Item: {
        id: "1",
        content: "content from DynamoDBDocumentClient",
        undefinedValue: undefined,
        emptyValue: "",
        numberValue: 42,
      },
    })
  );
  console.log(
    await ddbDocClient.send(new GetCommand({ TableName, Key: { id: "1" } }))
  );
  await ddbDocClient.send(new DeleteCommand({ TableName, Key: { id: "1" } }));

  await client.send(new DeleteTableCommand({ TableName }));
})();

{
  '$metadata': {
    httpStatusCode: 200,
    requestId: 'F8GF3NMJ44SG0GKNC2SLMIF8ARVV4KQNSO5AEMVJF66Q9ASUAAJG',
    extendedRequestId: undefined,
    cfId: undefined,
    attempts: 1,
    totalRetryDelay: 0
  },
  ConsumedCapacity: undefined,
  Item: {
    content: 'content from DynamoDBDocumentClient',
    emptyValue: null,
    numberValue: { value: '42' },
    id: '1'
  }
}

batchGet/batchWrite operations

import {
  BatchGetCommand,
  BatchWriteCommand,
  DynamoDBDocumentClient,
} from "../aws-sdk-js-v3/lib/lib-dynamodb";
import {
  DynamoDBClient,
  CreateTableCommand,
  waitForTableExists,
  DeleteTableCommand,
} from "../aws-sdk-js-v3/clients/client-dynamodb";

(async () => {
  const region = "us-west-2";
  const client = new DynamoDBClient({ region });

  const TableName = `test-${Math.ceil(Math.random() * 10 ** 10)}`;

  const params = {
    TableName,
    AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
    KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
    BillingMode: "PAY_PER_REQUEST",
  };

  await client.send(new CreateTableCommand(params));
  await waitForTableExists({ client, maxWaitTime: 30 }, { TableName });

  const ddbDocClient = DynamoDBDocumentClient.from(client);

  console.log(
    await ddbDocClient.send(
      new BatchWriteCommand({
        RequestItems: {
          [TableName]: [
            {
              PutRequest: {
                Item: {
                  id: "1",
                  content: "content #1 from DynamoDBDocumentClient",
                },
              },
            },
            {
              PutRequest: {
                Item: {
                  id: "2",
                  content: "content #2 from DynamoDBDocumentClient",
                },
              },
            },
          ],
        },
      })
    )
  );

  console.log(
    await ddbDocClient.send(
      new BatchGetCommand({
        RequestItems: {
          [TableName]: {
            Keys: [{ id: "1" }, { id: "2" }],
          },
        },
      })
    )
  );

  console.log(
    await ddbDocClient.send(
      new BatchWriteCommand({
        RequestItems: {
          [TableName]: [
            { DeleteRequest: { Key: { id: "1" } } },
            { DeleteRequest: { Key: { id: "2" } } },
          ],
        },
      })
    )
  );

  await client.send(new DeleteTableCommand({ TableName }));
})();

{
  '$metadata': {
    httpStatusCode: 200,
    requestId: 'POQM9UIVIA55OD14NAR4V6I7EJVV4KQNSO5AEMVJF66Q9ASUAAJG',
    extendedRequestId: undefined,
    cfId: undefined,
    attempts: 1,
    totalRetryDelay: 0
  },
  ConsumedCapacity: undefined,
  ItemCollectionMetrics: undefined,
  UnprocessedItems: {}
}
{
  '$metadata': {
    httpStatusCode: 200,
    requestId: 'K4NIL8JRT20AFG9GGLPT3UPSEVVV4KQNSO5AEMVJF66Q9ASUAAJG',
    extendedRequestId: undefined,
    cfId: undefined,
    attempts: 1,
    totalRetryDelay: 0
  },
  ConsumedCapacity: undefined,
  Responses: { 'test-915485136': [ [Object], [Object] ] },
  UnprocessedKeys: {}
}
{
  '$metadata': {
    httpStatusCode: 200,
    requestId: '3C6D84FO0DH8A8TTVG1NGRS6D3VV4KQNSO5AEMVJF66Q9ASUAAJG',
    extendedRequestId: undefined,
    cfId: undefined,
    attempts: 1,
    totalRetryDelay: 0
  },
  ConsumedCapacity: undefined,
  ItemCollectionMetrics: undefined,
  UnprocessedItems: {}
}

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[kyeotic]

Overall this is very good. Its the same API as the DB Client, abstracts all the marshalling, and is easy to construct.

There are some minor-to-medium inefficiencies that I've noted, but even if they are not resolved I would be happy to use this.

[AllanZhengYP]

Very solid PR. Had a few minor comments.

[AllanZhengYP]

We can put the utils back to the lib-dynamodb source code and not to overwrite it during the codegen. It would be easier to maintain.

[codecov-io]

Codecov Report

❗ No coverage uploaded for pull request base (main@c612c75). Click here to learn what that means.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #2097   +/-   ##
=======================================
  Coverage        ?   78.67%           
=======================================
  Files           ?      379           
  Lines           ?    16050           
  Branches        ?     3434           
=======================================
  Hits            ?    12628           
  Misses          ?     3422           
  Partials        ?        0           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c612c75...e324af4. Read the comment docs.

[aws-sdk-js-automation]

AWS CodeBuild CI Report

• CodeBuild project: sdk-staging-test
• Commit ID: 1af070e
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[AllanZhengYP]

Thank a lot for putting this together! 🚢

One of my previous nit comment was not addressed: comment.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.