@brightcove/dynamodb-connector

DynamoDB Connector

Provides a standardized way to connect to an AWS DynamoDB database using the v3 AWS javascript SDK.

Install

npm install @brightcove/dynamodb-connector --save

Usage

Version 2.x

const { DynamoDBConnector } = require('@brightcove/dynamodb-connector');

// Localstack configuration example
const db = new DynamoDBConnector({
    clientConfig: {
        endpoint: 'http://localhost:4566,
        region: 'us-east-1'
    }
});
...
const result = await db.query({
    TableName: 'my-table',
    ...
});

Options

Param	Type	Description	Required
clientConfig	DynamoDBClientConfig	https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-dynamodb/TypeAlias/DynamoDBClientConfigType	yes
translateConfig	TranslateConfig	https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/TypeAlias/TranslateConfig	no
logger	Logger	What will be used for logging errors (ie. logger.error()). console is used by default if not specified	no

Version 3.x

This version includes breaking changes by requiring the DynamoDBDocument to be passed in as an option. This drasticaly reduces the size of this package and removes all external dependencies.

import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBConnector } from '@brightcove/dynamodb-connector';

const client = new DynamoDBClient({
    endpoint: 'http://localhost:4566',
    region: 'us-east-1'
});
const document = DynamoDBDocument.from(client);

const db = new DynamoDBConnector({ document });
...
const result = await db.query({
    TableName: 'my-table',
    ...
});

Options

Param	Type	Description	Required
document	DynamoDBDocument	https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/DynamoDBDocument	yes

Functions

Query

const result = await db.query({
  TableName: "CoffeeCrop",
  KeyConditionExpression: "#primaryKey = :originCountry AND #sortKey > :roastDate",
  ExpressionAttributeNames: {
    "#primaryKey": "OriginCountry",
    "#sortKey": "RoastDate",
  },
  ExpressionAttributeValues: {
    ":originCountry": "Ethiopia",
    ":roastDate": "2023-05-01",
  },
});

console.log(result.Items); // And array of items that match the query

Including true as the second parameter will automatically get all items if result.LastEvaluatedKey is returned

const result = await db.query({
  TableName: "CoffeeCrop",
  KeyConditionExpression: "#primaryKey = :originCountry AND #sortKey > :roastDate",
  ExpressionAttributeNames: {
    "#primaryKey": "OriginCountry",
    "#sortKey": "RoastDate",
  },
  ExpressionAttributeValues: {
    ":originCountry": "Ethiopia",
    ":roastDate": "2023-05-01",
  },
}, true);

console.log(result.Items); // And array of items that match the query.

Get

const result = await db.get({
  TableName: "AngryAnimals",
  Key: {
    CommonName: "Shoebill",
  }
});

console.log(result.Item); // The requested item

Put

const result = await db.put({
  TableName: "HappyAnimals",
  Item: {
    CommonName: "Shiba Inu",
  },
});

ToUpdateExpressionFields

This provides a helper method for easily creating an entire update expression

const updates = {
  SET: [
    { key: '#last_login', value: new Date().toISOString() }
  ],
  ADD: [
    { key: '#num_login_attempts', value: 5 }
  ],
  REMOVE: [
    { key: '#not_logged_in' },
    { key: '#new_user' }
  ]
};

const { UpdateExpression, ExpressionAttributeValues,ExpressionAttributeNames } = db.toUpdateExpressionFields(updates);

console.log(UpdateExpression);
// SET #last_login = :last_login ADD #num_login_attempts :num_login_attempts REMOVE #not_logged_in, #new_user

console.log(ExpressionAttributeValues);
/**
{
  ":last_login": "2025-02-20T15:29:51.757Z",
  ":num_login_attempts": 5
}
*/

console.log(ExpressionAttributeNames);
/**
{
  "#last_login": "last_login",
  "#num_login_attempts": "num_login_attempts",
  "#not_logged_in": "not_logged_in",
  "#new_user": "new_user"
}
*/

Update

const result = await db.update({
  TableName: "Dogs",
  Key: {
    Breed: "Labrador",
  },
  UpdateExpression: "set Color = :color",
  ExpressionAttributeValues: {
    ":color": "black",
  },
  ReturnValues: "ALL_NEW",
});

console.log(result.Attributes); // The updated item

Delete

await db.delete({
  TableName: "Sodas",
  Key: {
    Flavor: "Cola",
  },
});

BatchGet

const keys = [{ Flavor: "Cola" }, { Flavor: "Sprite" }];

const result = await db.batchGet("Sodas", keys);

console.log(result.Items); // An array of the requested items

BatchWrite

const puts = [{ Flavor: "Cola" }, { Flavor: "Sprite" }]
  .map(db.toPutRequest);

const deletes = [{ Flavor: "Mountain Dew" }, { Flavor: "Dr. Pepper" }]
  .map((item) => db.toDeleteRequest(item, "Flavor"));

await db.batchWrite("Sodas", [ ...puts, ...deletes ]);

TransactWrite

const items = [
  {
    Put: {
      TableName: "HappyAnimals",
      Item: {
        Type: "Animal",
        Breed: "Shiba Inu",
      }
    }
  },
  {
    Update: {
      TableName: "Dogs",
      Key: {
        Type: "Animal",
        Breed: "Labrador",
      },
      UpdateExpression: "set Color = :color",
      ExpressionAttributeValues: {
        ":color": "black",
      },
      ReturnValues: "ALL_NEW",
    }
  }
];

await db.transactWrite(items);

TransactGet

const items = [
  {
    TableName: "Dogs",
    Key: {
      Type: "Animal",
      Breed: "Labrador",
    },
  },
  {
    TableName: "Dogs",
    Key: {
      Type: "Animal",
      Breed: "Shiba Inu",
    },
  }
];

const result = await db.transactGet(items);

console.log(result); // An array of the requested items

UUID

const uuid = db.uuid();

console.log(uuid); // A random UUIDv4