@aws-sdk/lib-dynamodb 3.686.0 → 3.689.0

package/README.md

@@ -120,15 +120,26 @@ export interface marshallOptions {
    * but false if directly using the marshall function (backwards compatibility).
    */
   convertTopLevelContainer?: boolean;
+  /**
+   * Whether to allow numbers beyond Number.MAX_SAFE_INTEGER during marshalling.
+   * When set to true, allows numbers that may lose precision when converted to JavaScript numbers.
+   * When false (default), throws an error if a number exceeds Number.MAX_SAFE_INTEGER to prevent
+   * unintended loss of precision. Consider using the NumberValue type from @aws-sdk/lib-dynamodb
+   * for precise handling of large numbers.
+   */
+  allowImpreciseNumbers?: boolean;
 }
 
 export interface unmarshallOptions {
   /**
-   * Whether to return numbers as a string instead of converting them to native JavaScript numbers.
+   * Whether to modify how numbers are unmarshalled from DynamoDB.
+   * When set to true, returns numbers as NumberValue instances instead of native JavaScript numbers.
    * This allows for the safe round-trip transport of numbers of arbitrary size.
+   *
+   * If a function is provided, it will be called with the string representation of numbers to handle
+   * custom conversions (e.g., using BigInt or decimal libraries).
    */
-  wrapNumbers?: boolean;
-
+  wrapNumbers?: boolean | ((value: string) => number | bigint | NumberValue | any);
   /**
    * When true, skip wrapping the data in `{ M: data }` before converting.
    *
@@ -235,10 +246,59 @@ const response = await client.get({
 const value = response.Item.bigNumber;
 ```
 
+You can also provide a custom function to handle number conversion during unmarshalling:
+
+```typescript
+const client = DynamoDBDocument.from(new DynamoDB({}), {
+  unmarshallOptions: {
+    // Use BigInt for all numbers
+    wrapNumbers: (str) => BigInt(str),
+  },
+});
+
+const response = await client.get({
+  Key: { id: 1 },
+});
+
+// Numbers in response will be BigInt instead of NumberValue or regular numbers
+```
+
 `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.
 
+The client protects against precision loss by throwing an error on large numbers, but you can either
+allow imprecise values with `allowImpreciseNumbers` or maintain exact precision using `NumberValue`.
+
+```typescript
+const preciseValue = "34567890123456789012345678901234567890";
+
+// 1. Default behavior - will throw error
+await client.send(
+  new PutCommand({
+    TableName: "Table",
+    Item: {
+      id: "1",
+      number: Number(preciseValue), // Throws error: Number is greater than Number.MAX_SAFE_INTEGER
+    },
+  })
+);
+
+// 2. Using allowImpreciseNumbers - will store but loses precision (mimics the v2 implicit behavior)
+const impreciseClient = DynamoDBDocumentClient.from(new DynamoDBClient({}), {
+  marshallOptions: { allowImpreciseNumbers: true },
+});
+await impreciseClient.send(
+  new PutCommand({
+    TableName: "Table",
+    Item: {
+      id: "2",
+      number: Number(preciseValue), // Loses precision 34567890123456790000000000000000000000n
+    },
+  })
+);
+```
+
 ### Client and Command middleware stacks
 
 As with other AWS SDK for JavaScript v3 clients, you can apply middleware functions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-sdk/lib-dynamodb",
-  "version": "3.686.0",
+  "version": "3.689.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",
@@ -29,17 +29,17 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@aws-sdk/core": "3.686.0",
-    "@aws-sdk/util-dynamodb": "3.686.0",
+    "@aws-sdk/util-dynamodb": "3.689.0",
     "@smithy/core": "^2.5.1",
     "@smithy/smithy-client": "^3.4.2",
     "@smithy/types": "^3.6.0",
     "tslib": "^2.6.2"
   },
   "peerDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.686.0"
+    "@aws-sdk/client-dynamodb": "^3.687.0"
   },
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "3.686.0",
+    "@aws-sdk/client-dynamodb": "3.687.0",
     "@tsconfig/recommended": "1.0.1",
     "@types/node": "^16.18.96",
     "concurrently": "7.0.0",