@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
logger	Logger	What will be used for logging errors (ie. logger.error()). console is used by default if not specified	no

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

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",
  },
});

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

ToUpdateExpression

const UpdateExpression = db.toUpdateExpression({
  SET: [
    { key: "Color", value: ":color" }
  ]
});

const result = await db.update({
  TableName: "Dogs",
  Key: {
    Breed: "Labrador",
  },
  UpdateExpression,
  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 ]);

UUID

const uuid = db.uuid();

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