# aws-dynamo-helper

> Library that makes it easy to work with AWS DynamoDB.

Latest version **1.0.5** (published 2017-09-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install aws-dynamo-helper
pnpm add aws-dynamo-helper
yarn add aws-dynamo-helper
bun add aws-dynamo-helper
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2017-09-28 |
| First published | 2017-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Igor Chernyy |
| Maintainers | glaciannex |
| Keywords | aws, dynamo, dynamodb |

## Links

- npm: https://www.npmjs.com/package/aws-dynamo-helper
- Repository: https://github.com/GlacianNex/aws-dynamo-lambda-helper
- Homepage: https://github.com/GlacianNex/aws-dynamo-lambda-helper#readme
- Issues: https://github.com/GlacianNex/aws-dynamo-lambda-helper/issues
- npm.io page: https://npm.io/package/aws-dynamo-helper

## Dependencies (4)

- [q](https://npm.io/package/q.md) *
- [aws-sdk](https://npm.io/package/aws-sdk.md) *
- [deepmerge](https://npm.io/package/deepmerge.md) ^1.5.0
- [dynamodb-marshaler](https://npm.io/package/dynamodb-marshaler.md) ^2.0.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.0.5 (latest) — 2017-09-28
- 1.0.4 — 2017-09-11
- 1.0.3 — 2017-08-12
- 1.0.2 — 2017-08-03
- 1.0.1 — 2017-06-26
- 1.0.0 — 2017-04-19

## README

# aws-dynamo-helper

Helper library designed to reduce amount of code needed to work with DynamoDB.

## Motivation

Working with DynamoDB has always been a pain. Even with new docClient from Amazon you still need quite a bit of code to perform simple operations. Lack of support for promises is another issue. I wanted to have a simple to use library that abstracted away a lot of boiler plate code.

## Usage

### DynamoDB Expressions

This library expects that you know how to write DynamoDB expressions. If you don't you can get familiar with them [here](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Syntax). Many methods will expect to get expression name and value maps, if you are not familiar why here are some references: [name maps](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html) and [value maps](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeValues.html).

All both attrbiutes will follow the same format in both cases.

#### Expression Example

`const expression = ':name = #value1 AND :year = #value2';`

#### Name Map - Example

` const nameMap = {
    ':name' : 'firstName',
    ':year' : 'makeYear'
};`

#### Value Map - Example

` const valueMap = {
    '#value1' : 'john',
    '#value2' : 1990
};`

### Constructor

``` js
const Dynamo = require('aws-dynamo-helper');
const db = new Dynamo(region, profile);
```

* awsRegion - region in which your DynamoDB is located, default: `process.env.AWS_DEFAULT_REGION`. *(optional)*
* profile - profile that will be used to get your AWS credentials. If none provided aws-sdk will follow its default chain to get credentials from your environment. *(optional)*

### Methods

Library supports following operations.

#### get

`db.get(tableName, hashAndRange)`

Fetches record from DynamoDB.

* tableName - name of the table *(required)*
* hashAndRange - is an object that follows format: `{ hashName: 'hashValue', rangeName : 'rangeValue'}`. If your table does not have range, ommit it. *(required)*

Example:

``` js
db.get('sampleTable', {
    patientId: '1',
    timestamp: 123456789
})
```

#### query

`db.query(tableName, keyExpression, filterExpression, nameMap, valueMap)`

Queries DynamoDB for a set of records that match specified pattern.

* tableName - name of the table *(required)*
* keyExpression - expression that will be used to filter your Key (hash and range) attributes.  **Query operation requires descrimination on key attributes** *(required)*
* filterExpression - expression that will be used to filter your non-Keys attributes *(optional)*
* nameMap - attribute name map that will map attributes used in key and filter expressions to proper names *(required)*
* valueMap - value map that will map values used in key and filter expressions to proper values *(required)*

Example:

``` js
db.query('sampleTable', ':name = #name', ':yr = #yr', { ':name' : 'firstName', ':yr' : 'makeYear'}, {'#yr' : 1990, '#name': 'john'}).
then((items) => {
    items.forEach((item) => console.log(item));
)}
```

#### update

`db.update(tableName, hashAndRange, updateExp, expNames, expValues)`

Updates a specific record in a table using update expression.

* tableName - name of the table *(required)*
* hashAndRange - is an object that follows format: `{ hashName: 'hashValue', rangeName : 'rangeValue'}`. If your table does not have range, ommit it. *(required)*
* updateExp - expression that will be used to update the record*(required)*
* expNames - attribute name map that will map attributes used in update expression to proper names *(required)*
* expValues - value map that will map values used in update expression to proper values *(required)*

Example:

``` js
db.update('sampleTable', { name: 'john' }, ':yr = #yr', { ':yr' : 'makeYear'}, {'#yr' : 1995}).
then(() => {
    console.log('success');
)}
```

#### delete

`db.delete(tableName, hashAndRange, conditionExp, expNames, expValues)`

Deletes a specific record or multiple records **(that share same hash)** in a table that match a conditional expression.

* tableName - name of the table *(required)*
* hashAndRange - is an object that follows format: `{ hashName: 'hashValue', rangeName : 'rangeValue'}`. If your table does not have range or you want to delete multiple items that share the same hash, ommit it. *(required)*
* conditionExp - expression that will be used to verify that record qualifies for deletion*(optional)*
* expNames - attribute name map that will map attributes used in condition expression to proper names *(optional)*
* expValues - value map that will map values used in condition expression to proper values *(optional)*

Example:

``` js
db.delete('sampleTable', { name: 'john' }, ':yr > #yr', { ':yr' : 'makeYear'}, {'#yr' : 1995}).
then((items) => {
    items.forEach((item) => console.log(`item deleted: ${item}`));
)}
```

#### store

`db.get(tableName, recordObj)`

Stores a single item into a table.

* tableName - name of the table *(required)*
* recordObject - object that you want to store, it must have proper hash and range keys set. *(required)*

Example:

``` js
db.store('sampleTable', {
    name: 'john',
    makeYear: 1989,
    taste: 'crappy'
})
```

## Conlusion

I hope this library is helpful! For any questions or comments feel free to reach out to me via GitHub [@glaciannex](https://github.com/GlacianNex).

---
_Source: https://npm.io/package/aws-dynamo-helper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._