DynamoDB Utilities

/**
 * Unmarshalls a DynamoDB AttributeValue to a JavaScript object.
 * The implementation is loosely based on the official AWS SDK v3 unmarshall function
 * but without customization options and with assumed support for BigInt.
 *
 * Supported DynamoDB types:
 * - NULL: converts to null
 * - S: string
 * - B: binary (Uint8Array)
 * - BS: binary set (Set<Uint8Array>)
 * - SS: string set (Set<string>)
 * - BOOL: boolean
 * - N: number (uses BigInt for large numbers beyond MAX_SAFE_INTEGER)
 * - NS: number set (Set<number | bigint>)
 * - L: list (Array)
 * - M: map (Object)
 *
 * @param data - The DynamoDB AttributeValue to unmarshall
 * @returns The unmarshalled JavaScript object
 * @throws UnmarshallDynamoDBAttributeError if unsupported type or invalid data
 */
function unmarshallDynamoDB(
  data: AttributeValue | Record<string, AttributeValue>
): unknown;

/**
 * Error thrown when unmarshalling DynamoDB attributes fails.
 */
class UnmarshallDynamoDBAttributeError extends Error {
  constructor(message: string);
}

import { unmarshallDynamoDB } from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';
import type { AttributeValue } from '@aws-sdk/client-dynamodb';

// Unmarshall a DynamoDB item
const item: Record<string, AttributeValue> = {
  id: { S: 'user-123' },
  name: { S: 'Alice' },
  age: { N: '30' },
  active: { BOOL: true },
};

const unmarshalled = unmarshallDynamoDB(item);
console.log(unmarshalled);
// {
//   id: 'user-123',
//   name: 'Alice',
//   age: 30,
//   active: true
// }

import { unmarshallDynamoDB } from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';

// Nested objects and arrays
const complexItem = {
  id: { S: 'order-456' },
  items: {
    L: [
      { M: { name: { S: 'Item 1' }, price: { N: '29.99' } } },
      { M: { name: { S: 'Item 2' }, price: { N: '49.99' } } },
    ],
  },
  tags: { SS: ['electronics', 'sale', 'new'] },
  metadata: {
    M: {
      createdAt: { S: '2024-01-01' },
      updatedAt: { S: '2024-01-02' },
    },
  },
};

const result = unmarshallDynamoDB(complexItem);
// {
//   id: 'order-456',
//   items: [
//     { name: 'Item 1', price: 29.99 },
//     { name: 'Item 2', price: 49.99 }
//   ],
//   tags: Set(['electronics', 'sale', 'new']),
//   metadata: {
//     createdAt: '2024-01-01',
//     updatedAt: '2024-01-02'
//   }
// }

import { unmarshallDynamoDB } from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';

// Numbers beyond MAX_SAFE_INTEGER are converted to BigInt
const largeNumberItem = {
  id: { S: 'transaction-789' },
  amount: { N: '9007199254740992' }, // Beyond MAX_SAFE_INTEGER
  smallAmount: { N: '100' },
};

const result = unmarshallDynamoDB(largeNumberItem);
// {
//   id: 'transaction-789',
//   amount: 9007199254740992n, // BigInt
//   smallAmount: 100 // regular number
// }

import { unmarshallDynamoDB } from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';

// String sets and number sets
const setItem = {
  id: { S: 'user-101' },
  roles: { SS: ['admin', 'user', 'editor'] },
  permissions: { NS: ['1', '2', '3', '4'] },
};

const result = unmarshallDynamoDB(setItem);
// {
//   id: 'user-101',
//   roles: Set(['admin', 'user', 'editor']),
//   permissions: Set([1, 2, 3, 4])
// }

// Working with the set
console.log(result.roles.has('admin')); // true
console.log(Array.from(result.permissions)); // [1, 2, 3, 4]

import {
  unmarshallDynamoDB,
  UnmarshallDynamoDBAttributeError,
} from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';

try {
  const invalidItem = {
    value: { UNSUPPORTED_TYPE: 'value' },
  };

  unmarshallDynamoDB(invalidItem);
} catch (error) {
  if (error instanceof UnmarshallDynamoDBAttributeError) {
    console.error('Failed to unmarshall:', error.message);
    // Handle the error appropriately
  }
}

import { DynamoDBClient, GetItemCommand } from '@aws-sdk/client-dynamodb';
import { unmarshallDynamoDB } from '@aws-lambda-powertools/commons/utils/unmarshallDynamoDB';

const client = new DynamoDBClient({});

// Get item from DynamoDB
const response = await client.send(
  new GetItemCommand({
    TableName: 'Users',
    Key: {
      id: { S: 'user-123' },
    },
  })
);

// Unmarshall the response
if (response.Item) {
  const user = unmarshallDynamoDB(response.Item);
  console.log(user);
}