From 4d6db9059ed5b026d21bcf9328c2ceb6197903ab Mon Sep 17 00:00:00 2001
From: Ran Vaknin <50976344+RanVaknin@users.noreply.github.com>
Date: Mon, 5 Feb 2024 06:54:46 -0700
Subject: [PATCH] =?UTF-8?q?docs(main):=20adding=20info=20about=20remove=20?=
 =?UTF-8?q?undefined=20values=20for=20doc=20client=20=E2=80=A6=20(#5725)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(main): adding info about remove undefined values for doc client marshalling

* docs(main): fixing code example to not use marshall function

* docs(main): fixing description for basic use section

---------

Co-authored-by: RanVaknin <RanVaknin@users.noreply.github.com>
---
 UPGRADING.md | 48 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/UPGRADING.md b/UPGRADING.md
index f27f88046728..b3a3e6855746 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -458,13 +458,17 @@ S3 client in v3 supports S3 global client, or following region redirects, if an
 
 ## DynamoDB Document Client
 
-In v2, you can use the [`AWS.DynamoDB.DocumentClient` class](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html)
-to call DynamoDB API with native JavaScript types like Buffer, Array, and Object. It thus simplifies working with items
-in Amazon DynamoDB by abstracting away the notion of attribute values.
+### Basic Usage of DynamoDB Document Client in v3
 
-In v3, equivalent [`@aws-sdk/lib-dynamodb`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html)
-is available. It's similar to normal service clients from v3 SDK, with the difference that it takes a basic DynamoDB
-client in its constructor. Here's an brief example:
+- In v2, you can use the [`AWS.DynamoDB.DocumentClient` class](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html)
+  to call DynamoDB API with native JavaScript types like Array, Number, and Object. It thus simplifies working with items
+  in Amazon DynamoDB by abstracting away the notion of attribute values.
+
+- In v3, the equivalent [`@aws-sdk/lib-dynamodb`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_lib_dynamodb.html)
+  is available. It's similar to normal service clients from v3 SDK, with the difference that it takes a basic DynamoDB
+  client in its constructor.
+
+Example:
 
 ```javascript
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // ES6 import
@@ -489,6 +493,38 @@ await ddbDocClient.send(
 );
 ```
 
+### `undefined` values in when marshalling
+
+- In v2 `undefined` values in objects were automatically omitted during the marshalling process to DynamoDB.
+
+- In v3, the default marshalling behavior in @aws-sdk/lib-dynamodb has changed: objects with `undefined` values are no longer omitted. To align with v2's functionality, developers must explicitly set the `removeUndefinedValues` to `true` in the `marshallOptions` of the DynamoDBDocumentClient.
+
+Example:
+
+```js
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+
+const client = new DynamoDBClient({});
+
+// The DynamoDBDocumentClient is configured to handle undefined values properly
+const ddbDocClient = DynamoDBDocumentClient.from(client, {
+  marshallOptions: {
+    removeUndefinedValues: true
+  }
+});
+
+await ddbDocClient.send(
+  new PutCommand({
+    TableName,
+    Item: {
+      id: "123",
+      content: undefined // This value will be automatically omitted
+    };
+  })
+);
+```
+
 More examples and configurations are available in the [package README](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-dynamodb/README.md).
 
 ## Waiters