node-aws-utilities

Collection of utilities to work with aws-sdk in node.js

Do you enjoy writing complex DynamoDB update expressions? Me neither.

Here comes node-aws-utilities, where in the future you would hopefully find some set of useful utilities and abstractions to make your work with aws services even simpler.

The repository was created as a necessity to solve some mundane, repetitive and error prone tasks.

If you have any idea for some useful utility that would make our lives easier feel free to contribute.

Installation

  npm install node-aws-utilities

Usage

Let's say we have an item in our FruitsTable as below:

  {
     fruitId: 'c9a74a1d-93a7-46ec-a3d0-654d33ddfd38',
     color: 'yellow',
     name: 'banana',
     taste: 'sweet',
     variant: {
      name: 'Cavendish',
      origin: { country: 'Mauritius', year: '1834' }
     }
  }

And we want to perform following changes:

• add new field variant.texture with value ["soft", "starchy"]
• add new field size with value small // TODO: This is incorrect, add/delete work only for sets, numbers
• remove field color with value yellow
• update variant.origin.year with value 1855
• update variant.origin.country with value Tahiti
• update variant.name with value Apple

With the help of createUpdateExpression you no longer need to create the update expression like below:

  import { DynamoDB } from 'aws-sdk'
  
  const documentClient = new DynamoDB.DocumentClient({...})
  
  const params = {
    TableName: 'FruitsTable',
    Key: { fruitId: 'c9a74a1d-93a7-46ec-a3d0-654d33ddfd38' },
    UpdateExpression:
      'add #p_variant.#p_texture :v_texture, #p_size :v_size \
       remove #p_color \
       set #p_variant.#p_origin.#p_year = :v_year, \
       #p_variant.#p_origin.#p_country = :v_country, \
       #p_variant.#p_name = :v_name'
    ExpressionAttributeNames: {
      '#p_variant': 'variant',
      '#p_texture': 'texture',
      '#p_size': 'size',
      '#p_color': 'color',
      '#p_origin': 'origin',
      '#p_year': 'year',
      '#p_country': 'country',
      '#p_name': 'name'
    },
    ExpressionAttributeValues: {
      ':v_texture': ['soft', 'starchy'],
      ':v_size': 'small',
      ':v_year': '1855',
      ':v_country': 'Tahiti'
      ':v_name': 'Apple'
    }
  }
  
  await documentClient.update(params).promise()

you can simply do it this way:

  import { DocumentClient, UpdateOperationType } from 'node-aws-utilities/dynamodb'
  
  const documentClient = new DocumentClient({...})
  
  const udateExpression = documentClient.createUpdateExpression(
    'FruitsTable',
    { fruitId: 'c9a74a1d-93a7-46ec-a3d0-654d33ddfd38' },
    {
      [UpdateOperationType.Add]: [{ variant: { texture: ['soft', 'starchy'] }, size: 'small' }],
      [UpdateOperationType.Remove]: [{ color: true }],
      [UpdateOperationType.Set]: [{ variant: { name: 'Apple', origin: { year: '1855', country: 'Tahiti' }}}]
    }
  )
  
  await documentClient.update(updateExpression).promise()

Default behaviour is to safely update object fields. Therefore not to overwrite the nested object with the new one. If you would like to force it simply mark the object with _replace. Don't worry, flag won't be populated to dynamodb. Example:

const udateExpression = documentClient.createUpdateExpression(
  'FruitsTable',
  { fruitId: 'c9a74a1d-93a7-46ec-a3d0-654d33ddfd38' },
  {
    [UpdateOperationType.Set]: [{ variant: { _replace: true, name: 'Apple', origin: { year: '1855', country: 'Tahiti' }}}]
  }
)

For lists current default behavior is to replace the whole list.

Work in progress..

Contribution

1. Make sure you have the following dependencies installed:

• node
• npm
• docker

2. Running unit tests:

  npm run test:unit

3. Running integration tests locally:

  npm run localstack
  npm run test:int