@aws-sdk/lib-dynamodb 3.438.0 → 3.441.0

package/README.md

@@ -20,18 +20,18 @@ Responses from DynamoDB are unmarshalled into plain JavaScript objects
 by the `DocumentClient`. The `DocumentClient` does not accept
 `AttributeValue`s 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                       |
+|          JavaScript Type           | DynamoDB AttributeValue |
+| :--------------------------------: | ----------------------- |
+|               String               | S                       |
+|   Number / BigInt / NumberValue    | N                       |
+|              Boolean               | BOOL                    |
+|                null                | NULL                    |
+|               Array                | L                       |
+|               Object               | M                       |
+|    Set\<Uint8Array, Blob, ...\>    | BS                      |
+| Set\<Number, BigInt, NumberValue\> | NS                      |
+|           Set\<String\>            | SS                      |
+| Uint8Array, Buffer, File, Blob...  | B                       |
 
 ### Example
 
@@ -98,20 +98,48 @@ const ddbDocClient = DynamoDBDocument.from(client); // client is DynamoDB client
 The configuration for marshalling and unmarshalling can be sent as an optional
 second parameter during creation of document client as follows:
 
-```js
-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.
-};
+```ts
+export interface marshallOptions {
+  /**
+   * Whether to automatically convert empty strings, blobs, and sets to `null`
+   */
+  convertEmptyValues?: boolean;
+  /**
+   * Whether to remove undefined values while marshalling.
+   */
+  removeUndefinedValues?: boolean;
+  /**
+   * Whether to convert typeof object to map attribute.
+   */
+  convertClassInstanceToMap?: boolean;
+  /**
+   * Whether to convert the top level container
+   * if it is a map or list.
+   *
+   * Default is true when using the DynamoDBDocumentClient,
+   * but false if directly using the marshall function (backwards compatibility).
+   */
+  convertTopLevelContainer?: boolean;
+}
+
+export interface unmarshallOptions {
+  /**
+   * Whether to return numbers as a string instead of converting them to native JavaScript numbers.
+   * This allows for the safe round-trip transport of numbers of arbitrary size.
+   */
+  wrapNumbers?: boolean;
+
+  /**
+   * When true, skip wrapping the data in `{ M: data }` before converting.
+   *
+   * Default is true when using the DynamoDBDocumentClient,
+   * but false if directly using the unmarshall function (backwards compatibility).
+   */
+  convertWithoutMapWrapper?: boolean;
+}
+
+const marshallOptions: marshallOptions = {};
+const unmarshallOptions: unmarshallOptions = {};
 
 const translateConfig = { marshallOptions, unmarshallOptions };
 
@@ -160,6 +188,57 @@ await ddbDocClient.put({
 });
 ```
 
+### Large Numbers and `NumberValue`.
+
+On the input or marshalling side, the class `NumberValue` can be used
+anywhere to represent a DynamoDB number value, even small numbers.
+
+```ts
+import { DynamoDB } from "@aws-sdk/client-dynamodb";
+import { NumberValue, DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
+
+// Note, the client will not validate the acceptability of the number
+// in terms of size or format.
+// It is only here to preserve your precise representation.
+const client = DynamoDBDocument.from(new DynamoDB({}));
+
+await client.put({
+  Item: {
+    id: 1,
+    smallNumber: NumberValue.from("123"),
+    bigNumber: NumberValue.from("1000000000000000000000.000000000001"),
+    nSet: new Set([123, NumberValue.from("456"), 789]),
+  },
+});
+```
+
+On the output or unmarshalling side, the class `NumberValue` is used
+depending on your setting for the `unmarshallOptions` flag `wrapnumbers`,
+shown above.
+
+```ts
+import { DynamoDB } from "@aws-sdk/client-dynamodb";
+import { NumberValue, DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
+
+const client = DynamoDBDocument.from(new DynamoDB({}));
+
+const response = await client.get({
+  Key: {
+    id: 1,
+  },
+});
+
+/**
+ * Numbers in the response may be a number, a BigInt, or a NumberValue depending
+ * on how you set `wrapNumbers`.
+ */
+const value = response.Item.bigNumber;
+```
+
+`NumberValue` does not provide a way to do mathematical operations on itself.
+To do mathematical operations, take the string value of `NumberValue` by calling
+`.toString()` and supply it to your chosen big number implementation.
+
 ### Client and Command middleware stacks
 
 As with other AWS SDK for JavaScript v3 clients, you can apply middleware functions

package/dist-cjs/index.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NumberValue = void 0;
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./DynamoDBDocument"), exports);
 tslib_1.__exportStar(require("./DynamoDBDocumentClient"), exports);
 tslib_1.__exportStar(require("./commands"), exports);
 tslib_1.__exportStar(require("./pagination"), exports);
+var util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+Object.defineProperty(exports, "NumberValue", { enumerable: true, get: function () { return util_dynamodb_1.NumberValueImpl; } });

package/dist-es/index.js

@@ -2,3 +2,4 @@ export * from "./DynamoDBDocument";
 export * from "./DynamoDBDocumentClient";
 export * from "./commands";
 export * from "./pagination";
+export { NumberValueImpl as NumberValue } from "@aws-sdk/util-dynamodb";

package/dist-types/index.d.ts

@@ -2,3 +2,4 @@ export * from "./DynamoDBDocument";
 export * from "./DynamoDBDocumentClient";
 export * from "./commands";
 export * from "./pagination";
+export { NumberValueImpl as NumberValue } from "@aws-sdk/util-dynamodb";

package/dist-types/ts3.4/index.d.ts

@@ -2,3 +2,4 @@ export * from "./DynamoDBDocument";
 export * from "./DynamoDBDocumentClient";
 export * from "./commands";
 export * from "./pagination";
+export { NumberValueImpl as NumberValue } from "@aws-sdk/util-dynamodb";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-sdk/lib-dynamodb",
-  "version": "3.438.0",
+  "version": "3.441.0",
   "description": "The document client simplifies working with items in Amazon DynamoDB by abstracting away the notion of attribute values.",
   "main": "./dist-cjs/index.js",
   "module": "./dist-es/index.js",
@@ -26,14 +26,14 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@aws-sdk/util-dynamodb": "3.438.0",
+    "@aws-sdk/util-dynamodb": "3.441.0",
     "tslib": "^2.5.0"
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "3.438.0",
+    "@aws-sdk/client-dynamodb": "3.441.0",
     "@smithy/smithy-client": "^2.1.12",
     "@smithy/types": "^2.4.0",
     "@tsconfig/recommended": "1.0.1",