Dynamo Request Builder

An intuitive DynamoDB request building API for JavaScript.

Contents

• Installation
• Creating Requests
• Attributes
• Logical Operators
• Executing Requests

Installation

npm install dynamo-request-builder

Creating Requests

Use the DynamoRequestBuilderCreator with a DynamoDB DocumentClient to create a DynamoRequestBuilder.

import DynamoRequestBuilderCreator from "dynamo-request-builder";

const requestBuilder = new DynamoRequestBuilderCreator(dynamoDocClient).create("table_name");

Delete

import { attribute, sizeOf } from "dynamo-request-builder/attributes";
import { or } from "dynamo-request-builder/operators";
import { ReturnValues } from "dynamo-request-builder/return-values";

const request = requestBuilder.delete("partitionKeyName", "partitionKeyValue")
  .withSortKey("sortKeyName", "sortKeyValue") // Sort key condition
  .onlyIfAttribute("attribute").eq("value") // Add an attribute condition
  .onlyIfSizeOfAttribute("attribute").lte(1) // Add a size of attribute condition
  .onlyIf(
    or(attribute("attribute1").gte(1), attribute("attribute2").contains("value")),
    sizeOf("attribute3").eq(2)
  ) // Add multiple attribute conditions
  .returnValues(ReturnValues.AllOld); // Specify values to return

Get

const request = requestBuilder.get("partitionKeyName", "partitionKeyValue")
  .withSortKey("sortKeyName", "sortKeyValue") // Sort key condition
  .getAttributes("attribute", "attribute[0]", "attribute[0].subAttribute") // Specify attributes to retrieve
  .consistentRead(); // Use consistent read

Put

import { attribute, sizeOf } from "dynamo-request-builder/attributes";
import { not } from "dynamo-request-builder/operators";
import { ReturnValues } from "dynamo-request-builder/return-values";

const item = {
  ...
};

const request = requestBuilder.put(item)
  .ifItemNotExists("partitionKeyName", "sortKeyName") // Only put the item if it doesn't already exist
  .onlyIfAttribute("attribute").eq("value") // Add an attribute condition
  .onlyIfSizeOfAttribute("attribute").lte(1) // Add a size of attribute condition
  .onlyIf(
	  not(attribute("attribute1").gte(1)),
	  sizeOf("attribute3").eq(2)
  ) // Add multiple attribute conditions
  .returnValues(ReturnValues.AllOld); // Specify values to return

Query

import { attribute, sizeOf } from "dynamo-request-builder/attributes";
import { or } from "dynamo-request-builder/operators";

const request = requestBuilder.query("partitionKeyName", "partitionKeyValue")
  .whereSortKey("sortKeyName").beginsWith("value") // Add a sort key condition
  .whereAttribute("attribute").eq("value") // Add an attribute condition
  .whereSizeOfAttribute("attribute").lt(1) // Add a size of attribute condition
  .where(
    or(attribute("attribute1").gte(1), attribute("attribute2").contains("value")),
    sizeOf("attribute3").eq(2)
  ) // Add multiple attribute conditions
  .getAttributes("attribute", "attribute[0]", "attribute[0].subAttribute") // Specify attributes to retrieve
  .limit(5) // Specify a limit on the number of items to return
  .useIndex("indexName") // Specify an index to use
  .scanIndexDescending(); // Scan the index in descending order

Scan

import { attribute, sizeOf } from "dynamo-request-builder/attributes";
import { or } from "dynamo-request-builder/operators";

const request = requestBuilder.scan()
  .whereAttribute("attribute").eq("value") // Add an attribute condition
  .whereSizeOfAttribute("attribute").lt(1) // Add a size of attribute condition
  .where(
    or(attribute("attribute1").gte(1), attribute("attribute2").contains("value")),
    sizeOf("attribute3").eq(2)
  ) // Add multiple attribute conditions
  .getAttributes("attribute", "attribute[0]", "attribute[0].subAttribute") // Specify attributes to retrieve
  .limit(5) // Specify a limit on the number of items to return
  .useIndex("indexName") // Specify an index to use

Update

import { attribute, sizeOf, update } from "dynamo-request-builder/attributes";
import { or } from "dynamo-request-builder/operators";

const request = requestBuilder.update("partitionKeyName", "partitionKeyValue")
  .withSortKey("sortKeyName", "sortKeyValue") // Sort key condition
  .updateAttribute("attribute").incrementBy(5) // Add an update operation
  .operations(update("attribute1").add(1, 2, 3), update("attribute2").remove()) // Add multiple update operations
  .onlyIfAttribute("attribute").eq("value") // Add an attribute condition
  .onlyIfSizeOfAttribute("attribute").lte(1) // Add a size of attribute condition
  .onlyIf(
    or(attribute("attribute1").gte(1), attribute("attribute2").contains("value")),
    sizeOf("attribute3").eq(2)
  ) // Add multiple attribute conditions
  .returnValues(UpdateReturnValues.UpdatedNew); // Specify values to return

You can check the generated request parameters for yourself by accessing request.params.

Attributes

The ability to select specific attributes and apply constraint conditions and update operations to them are needed for certain expressions.

Logical Operators

Logical operators are used to extend the logic of condition expressions, filter expressions and key condition expressions.

Executing Requests

Once a request has been created, it can be executed and the return values can be used.