Registry / aws / dynamodb-data-types

dynamodb-data-types

library4.0.1jsnpmunverified

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.

aws serialization

npm install dynamodb-data-types

github ↗package ↗

INSTALL

IMPORT

SIG · DYNAMODB-DATA-TYPE

dynamodb-data-types

awsjavascriptv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AttributeValue

✓ import { AttributeValue } from 'dynamodb-data-types';

✗ const AttributeValue = require('dynamodb-data-types').AttributeValue;

CommonJS `require` is shown in the README, but modern Node.js and browser environments should prefer ESM `import`. `AttributeValue` provides `wrap`, `unwrap`, `wrap1`, `unwrap1`.

updateExpr

✓ import { updateExpr } from 'dynamodb-data-types';

✗ const updateExpr = require('dynamodb-data-types').updateExpr;

The `updateExpr` function is a factory for building DynamoDB `UpdateExpression` objects and was introduced in v4.0.0. It's a named export.

wrap

✓ import { AttributeValue } from 'dynamodb-data-types'; const wrappedData = AttributeValue.wrap(data);

✗ import { wrap } from 'dynamodb-data-types';

`wrap` and `unwrap` are methods of the `AttributeValue` object, not direct named exports from the package root.

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.

import { AttributeValue, updateExpr } from 'dynamodb-data-types'; async function demonstrateDynamoDBUtils() { const originalData = { id: 'user#123', username: 'jsmith', email: 'jsmith@example.com', age: 30, preferences: { theme: 'dark', notifications: true }, tags: ['active', 'premium'], lastLogin: null }; // Marshalling JavaScript object to DynamoDB format const marshalledData = AttributeValue.wrap(originalData); console.log('Marshalled Data:', JSON.stringify(marshalledData, null, 2)); // Expected: { id: {S: 'user#123'}, username: {S: 'jsmith'}, ... } // Unmarshalling DynamoDB format back to JavaScript object const unmarshalledData = AttributeValue.unwrap(marshalledData); console.log('Unmarshalled Data:', JSON.stringify(unmarshalledData, null, 2)); // Expected: { id: 'user#123', username: 'jsmith', ... } // Building an UpdateExpression for a DynamoDB UpdateItem API call const updatePayload = updateExpr() .set({ email: 'john.smith@example.com', 'preferences.theme': 'light' // Nested attributes supported }) .add({ age: 1 }) // Increment age by 1 .remove('lastLogin') .delete({ tags: ['active'] }) // Remove 'active' from the tags set/list .expr(); // Generate the final expression object console.log('Update Expression Payload:', JSON.stringify(updatePayload, null, 2)); /* Expected: { UpdateExpression: "SET email = :a, #A.#B = :b ADD age :c REMOVE lastLogin DELETE tags :d", ExpressionAttributeValues: { ":a": {"S":"john.smith@example.com"}, ":b": {"S":"light"}, ":c": {"N":"1"}, ":d": {"SS":["active"]} }, ExpressionAttributeNames: { "#A":"preferences", "#B":"theme" } } */ } demonstrateDynamoDBUtils();

Debug

Known issues

breakingVersion 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.

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`.

affects: >=4.0.0

gotchaWhen 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.

fix

Always append `.expr()` to the `updateExpr()` method chain, e.g., `updateExpr().set({ key: 'value' }).expr();`

affects: >=4.0.0

gotchaDynamoDB'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).

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.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'wrap')

Attempting to call `wrap` directly from the package import instead of through `AttributeValue`.

fix

Use `import { AttributeValue } from 'dynamodb-data-types';` then call `AttributeValue.wrap(data)`.

The provided expression refers to an attribute that does not exist in the item.

Attempting to use `REMOVE` or `DELETE` on an attribute that is not present, or trying to remove specific elements from a non-set type.

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.

ValidationException: An ExpressionAttribute value is not defined for the SET update expression.

Incorrectly constructing the `SET` clause in an `UpdateExpression`, often by providing an empty object or invalid values.

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.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/kayomarz/dynamodb-data-types ↗

packagehttps://www.npmjs.com/package/dynamodb-data-types ↗