DynamoDB Expressions Builder

An easy and semantic way to build DynamoDB expressions

Example 1: Building DynamoDB Query expressions

// Build your query based on the partition and sort keys
const keyConditionDefinition = AND(
  EQ(PATH('partition'), LITERAL('order-index-by-city::NEW_YORK')),
  BETWEEN(PATH('sort'), LITERAL('STORE1_2022-01-01'), LITERAL('STORE1_2022-02-01')),
);

// Filter the queried items based on other attribute conditions
const filterDefinition = OR(
  EQ(PATH('status'), LITERAL('PENDING')),
  EQ(PATH('status'), LITERAL('PAID')),
);

// Fetch only the useful attributes to reduce data transfer
const projectionDefinition = PROJECTION('id', 'status', 'payments[0].amount');

/**
 * ...
 * You can pass the definition around to allow other components modify them
 * ...
 **/

// Once the definitions are ready, serialize them and perform the request using the DynamoDB DocumentClient
const expressions = SERIALIZE({ keyConditionDefinition, filterDefinition, projectionDefinition });
const { Items } = await client.query({ TableName: 'table', ...expressions }).promise();

/**
 * inspecting the serialized expressions...
 */

expressions.ConditionExpression;
// (#attr0 = :val1) AND (#attr2 BETWEEN :val3 AND :val4)

expressions.FilterExpression;
// (#attr5 = :val6) OR (#attr5 = :val7)

expressions.ProjectionExpression;
// #attr5, #attr8[0].#attr9, #attr10

expressions.ExpressionAttributeNames;
// { '#attr0': 'partition', '#attr2': 'sort', '#attr5': 'statu... }

expressions.ExpressionAttributeValues;
// { ':val1': 'order-index-by-city::NEW_YORK', ':val3': 'STORE1_202... }

Example 2: Building DynamoDB Update expressions

// Define what will be updated
const updateDefinition = UPDATE(
  // Set the value of some attribute by path
  SET('document.version', LITERAL('2.1.0')),
  // Creating a DynamoDB Set of numbers using DocumentClient.createSet
  SET('set-of-numbers', LITERAL(client.createSet([1, 2, 3]))),
  // Increment the value of some attribute
  SET('counters.views', SUM(PATH('counters.views'), LITERAL(1))),
  // Add item to a list
  SET('products', LIST_APPEND(PATH('products'), LITERAL({ sku: 1234 }))),
  // Set only if not exists
  SET('noOverwrite', IF_NOT_EXISTS(PATH('noOverwrite'), LITERAL(23))),
  // Set some complex object
  SET('object', LITERAL({ key: ['some complex object'] })),
  // Remove some attribute
  REMOVE('orders[0].payments[0].flag'),
  // Add an item to a set
  ADD('tags', docClient.createSet(['teste', 'tst'])),
  // Remove an item from a set
  DELETE('tags', docClient.createSet(['teste', 'tst'])),
  // some complex expression
  SET(
    'counters.views',
    SUM(
      IF_NOT_EXISTS(
        PATH('counters.views'),
        PATH('counters.conversions')
      ),
      IF_NOT_EXISTS(
        PATH('counters.clicks'),
        LITERAL(5)
      ),
    )
  ),
);

// Define conditions to perform the update
const conditionDefinition = OR(
  LT(PATH('createdAt'), LITERAL('2021-01-02T00:02:12.102Z')),
  AND(
    EQ(PATH('status'), LITERAL('PENDING')),
    GE(PATH('version'), LITERAL(100))
  ),
);

const expression = SERIALIZE({ updateDefinition, conditionDefinition });
await client.update({ TableName: 'table', Key={ ... }, ...expression }).promise();

The library supports these DynamoDB expressions:

• KeyConditionExpression
• FilterExpression
• ConditionExpression
• UpdateExpression
• ProjectionExpression

Next Steps

We're currently extensively testing the library and planning library interfaces improvements for the next releases

Installation

$ npm install dynamodb-expressions-builder

see on npm

Author

William Tutihashi