{"id":10772,"library":"dynamodb-data-types","title":"DynamoDB Data Type Marshaller and Update Expression Builder","description":"dynamodb-data-types is a JavaScript utility library designed to simplify the interaction with Amazon DynamoDB's native data type representations. It provides functions to convert standard JavaScript objects into DynamoDB's attribute value format (marshalling) and vice-versa (unmarshalling), handling complex nested structures and various primitive types. The library's current stable version is 4.0.1. Its release cadence is moderate, with major versions introducing significant features like the `UpdateExpression` builder in v4.0.0. A key differentiator is its focus on accurately handling DynamoDB's specific type mappings (e.g., numbers as strings `{N: '1'}`, sets, lists, maps, booleans, and nulls), alongside its ability to construct complex `UpdateExpression` payloads, including automatic handling of DynamoDB reserved keywords and proper `ExpressionAttributeValues` and `ExpressionAttributeNames` generation. This functionality reduces boilerplate code and common errors when performing update operations.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/kayomarz/dynamodb-data-types","tags":["javascript","dynamodb data types","dynamodb marshall","dynamodb format attributes","dynamodb mapper","amazon","aws"],"install":[{"cmd":"npm install dynamodb-data-types","lang":"bash","label":"npm"},{"cmd":"yarn add dynamodb-data-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add dynamodb-data-types","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS `require` is shown in the README, but modern Node.js and browser environments should prefer ESM `import`. `AttributeValue` provides `wrap`, `unwrap`, `wrap1`, `unwrap1`.","wrong":"const AttributeValue = require('dynamodb-data-types').AttributeValue;","symbol":"AttributeValue","correct":"import { AttributeValue } from 'dynamodb-data-types';"},{"note":"The `updateExpr` function is a factory for building DynamoDB `UpdateExpression` objects and was introduced in v4.0.0. It's a named export.","wrong":"const updateExpr = require('dynamodb-data-types').updateExpr;","symbol":"updateExpr","correct":"import { updateExpr } from 'dynamodb-data-types';"},{"note":"`wrap` and `unwrap` are methods of the `AttributeValue` object, not direct named exports from the package root.","wrong":"import { wrap } from 'dynamodb-data-types';","symbol":"wrap","correct":"import { AttributeValue } from 'dynamodb-data-types'; const wrappedData = AttributeValue.wrap(data);"}],"quickstart":{"code":"import { AttributeValue, updateExpr } from 'dynamodb-data-types';\n\nasync function demonstrateDynamoDBUtils() {\n  const originalData = {\n    id: 'user#123', \n    username: 'jsmith',\n    email: 'jsmith@example.com',\n    age: 30,\n    preferences: { \n      theme: 'dark', \n      notifications: true \n    },\n    tags: ['active', 'premium'],\n    lastLogin: null\n  };\n\n  // Marshalling JavaScript object to DynamoDB format\n  const marshalledData = AttributeValue.wrap(originalData);\n  console.log('Marshalled Data:', JSON.stringify(marshalledData, null, 2));\n  // Expected: { id: {S: 'user#123'}, username: {S: 'jsmith'}, ... }\n\n  // Unmarshalling DynamoDB format back to JavaScript object\n  const unmarshalledData = AttributeValue.unwrap(marshalledData);\n  console.log('Unmarshalled Data:', JSON.stringify(unmarshalledData, null, 2));\n  // Expected: { id: 'user#123', username: 'jsmith', ... }\n\n  // Building an UpdateExpression for a DynamoDB UpdateItem API call\n  const updatePayload = updateExpr()\n    .set({ \n      email: 'john.smith@example.com', \n      'preferences.theme': 'light' // Nested attributes supported\n    })\n    .add({ age: 1 }) // Increment age by 1\n    .remove('lastLogin')\n    .delete({ tags: ['active'] }) // Remove 'active' from the tags set/list\n    .expr(); // Generate the final expression object\n\n  console.log('Update Expression Payload:', JSON.stringify(updatePayload, null, 2));\n  /* Expected: \n    {\n      UpdateExpression: \"SET email = :a, #A.#B = :b ADD age :c REMOVE lastLogin DELETE tags :d\",\n      ExpressionAttributeValues: { \":a\": {\"S\":\"john.smith@example.com\"}, \":b\": {\"S\":\"light\"}, \":c\": {\"N\":\"1\"}, \":d\": {\"SS\":[\"active\"]} },\n      ExpressionAttributeNames: { \"#A\":\"preferences\", \"#B\":\"theme\" }\n    } \n  */\n}\n\ndemonstrateDynamoDBUtils();","lang":"typescript","description":"Demonstrates marshalling/unmarshalling JavaScript objects to DynamoDB format and building a complex `UpdateExpression` with `SET`, `ADD`, `REMOVE`, and `DELETE` clauses, including handling nested attributes and reserved keywords."},"warnings":[{"fix":"Review the README and update code to use the new `updateExpr()` API for generating UpdateExpressions. For marshalling/unmarshalling, ensure you are still using `AttributeValue.wrap` and `AttributeValue.unwrap`.","message":"Version 4.0.0 introduced significant changes to the API, most notably the addition of the `updateExpr()` builder. While `AttributeValue.wrap` and `unwrap` largely remained the same, direct access to some internal utilities might have changed.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always append `.expr()` to the `updateExpr()` method chain, e.g., `updateExpr().set({ key: 'value' }).expr();`","message":"When using `updateExpr()`, ensure you call `.expr()` at the end of your chain to generate the final `UpdateExpression` object. Forgetting this will result in returning the builder instance instead of the desired expression.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Consult the AWS DynamoDB documentation on `UpdateExpressions` to understand the precise behavior of each clause and use the appropriate `updateExpr()` method (`set`, `add`, `remove`, `delete`) for your intended operation.","message":"DynamoDB's `UpdateExpression` clauses (SET, ADD, REMOVE, DELETE) have specific behaviors. For instance, `ADD` can increment numbers or add items to sets, but cannot append to lists. `DELETE` is for removing elements from sets, not for deleting entire attributes (which `REMOVE` does).","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import { AttributeValue } from 'dynamodb-data-types';` then call `AttributeValue.wrap(data)`.","cause":"Attempting to call `wrap` directly from the package import instead of through `AttributeValue`.","error":"TypeError: Cannot read properties of undefined (reading 'wrap')"},{"fix":"Ensure the attribute exists before attempting `REMOVE` and verify that `DELETE` is only used for set types with appropriate values. Consider using `SET` with `null` if the intent is to clear an attribute's value rather than remove the attribute entirely.","cause":"Attempting to use `REMOVE` or `DELETE` on an attribute that is not present, or trying to remove specific elements from a non-set type.","error":"The provided expression refers to an attribute that does not exist in the item."},{"fix":"Ensure that the object passed to `.set()` contains valid key-value pairs representing the attributes to be set, and that values are of appropriate JavaScript types that can be marshalled by the library.","cause":"Incorrectly constructing the `SET` clause in an `UpdateExpression`, often by providing an empty object or invalid values.","error":"ValidationException: An ExpressionAttribute value is not defined for the SET update expression."}],"ecosystem":"npm"}