@szanata/dynamodb-helper v1.3.1

DynamoDB Helper

Abstract common AWS DynamoDB operations to use mainly on Lambdas

Installation & Configuration

npm install dynamodb-helper

And assuming your have AWS_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in your ENV, your are done.

Convetion on usage

The first argument is always the table name

Methods

• findByKey
• put
• putBatch
• query
• queryPage
• remove
• removeBatch
• scan
• scanPage
• update
• smartUpdate

findByKey

Fetch one record by its exaclty key

const dbHelper = require( 'dynamodb-helper' );

const record = await dbHelper.findByKey( 'table', { id: 'keyValue' } );

Arguments: table and key which is an object containing the key structure of the table.

put

Insert/update a record

const dbHelper = require( 'dynamodb-helper' );

const record = await dbHelper.put( 'table', object );

Arguments: table and object which is a full record to be inserted, or updated if its key is already present in the database.

putBatch

Insert/update an array of objects

const dbHelper = require( 'dynamodb-helper' );

const record = await dbHelper.put( 'table', arrayOfObjects );

Arguments: table and arrayOfObjects which is an array containing each of the records to be inserted or updated.

query

Queries the database according to given attributes, does it recursivelly if dynamo returns a pagination key. It will keep processing until it reaches the last page or the limit in the query.

const dbHelper = require( 'dynamodb-helper' );

const records = await dbHelper.query( 'table', nativeExpressions, opts );

Arguments: table and nativeExpressions are the default dynamo expressions for a query, except you can do it in camelCase.

Returns an Object with items, count and lastEvaluatedKey properties.

queryPage

Queries the database according to given attributes, return the items and the next pagination key (if some).

const dbHelper = require( 'dynamodb-helper' );

const { items, lastEvaluatedKey } = await dbHelper.queryPage( 'table', nativeExpressions, paginationKey );

Arguments: table and nativeExpressions are the default dynamo expressions for a query, except you can do it in camelCase. The paginationKey is the key returned by a previous call to this method.

Returns an Object with items, count and lastEvaluatedKey properties.

remove

Removes an single item in the database by its key object.

const dbHelper = require( 'dynamodb-helper' );

const deletedRecord = await dbHelper.remove( 'table', key );

Arguments: table and key, the object containing the primary key (hash key, or depending on the table hash + range keys).

Returns the deleted record.

removeBatch

Same as remove, but does it using the batch API.

const dbHelper = require( 'dynamodb-helper' );

const operationNativeResult = await dbHelper.removeBatch( 'table', keys );

Arguments: table and keys, and array containing each record primary key to remove.

Returns the native AWS DynamoDB result.

scan

Same as query but does it with .scan.

scanPage

Same as scanPage but does it with .scan.

update

Perform an update on some record using DynamoDB syntax.

const dbHelper = require( 'dynamodb-helper' );

const updatedRecord = await dbHelper.update( 'table', nativeExpression );

// a better example:
await dbHelper.update( 'table', {
  keyConditions: '#f = :f',
  conditionExpression: '#b = :b',
  expressionAttributeNames: {
    '#f': 'foo',
    '#b': 'bar'
  },
  expressionAttributeValues: {
    ':f': 'some value',
    ':b': 'some value'
  }
} );

Arguments: table and nativeExpressions, an update expression using Dynamo's syntax, except you can do it in camelCase. You can omit the table name, as it is the first argument.

smartUpdate

Creates the update expression for you based on values that changed according to the args

const dbHelper = require( 'dynamodb-helper' );

const record = await dbHelper.smartUpdate( 'table', { key: 'id' }, {
  'path.to.field' value
} );

Arguments: table, key which is key to the record to be updated and updateValues which is an object where the keys are the paths to each property (column) to be updated on the record - if property is a map, you referenced nested properties with nested notation 'path.to.field' - and the values are the new values to be set.

The smart update do a findByKey query before hand, fetch the current object, and build an update expression with the fields which really changed, ignoring the others.

If you pass a key to a record that does not exists in the databased, an error is thrown