exciter

An easy CRUD wrapper for DynamoDB. Working with the DynamoDB SDK is difficult. Exciter abstracts a lot of the DynamoDB-isms away leaving you an intuitive interface for performing CRUD operations on DynamoDB.

Usage

const Exciter = require('exciter');
const exciter = new Exciter();
const data = {
  id: '1f9a72be-bcc1-4552-aec0-53a8bc377bb5',
  things: 'to store in DynamoDB',
};
const primaryKey = { id: data.id };
const tableName = 'someTable';

// Create a record.
exciter.create(data, primaryKey, tableName)
  .then((awsResponse) => {
    // Creation was successful, now we can do something with the response.
  });

// Update a record. Each top-level property provided in data will be replaced.
exciter.update(data, primaryKey, tableName)
  .then((awsResponse) => {
    // Update was successful, now we can do something with the response.
  });

// Put a record. The entire entity will be replaced.
exciter.put(data, primaryKey, tableName)
  .then((awsResponse) => {
    // Put was successful, now we can do something with the response.
  });

// Load a record.
exciter.load(primaryKey, tableName)
  .then((awsResponse) => {
    // Load was successful, now we can do something with the response.
  });

// Query for records.
exciter.query(primaryKey, tableName)
  .then((awsResponse) => {
    // Query was successful, now we can do something with the response.
  });

// Delete a record.
exciter.delete(primaryKey, tableName)
  .then((awsResponse) => {
    // Delete was successful, now we can do something with the response.
  });

Classes

Typedefs

Exciter

Class representing a DynamoDB connection

Kind: global class

• Exciter
  • new Exciter(options, [rejectOnFail])
  • instance
    • .create(data, primaryKey, table) ⇒ Promise
    • .update(data, primaryKey, table) ⇒ Promise
    • .put(data, primaryKey, table, createOnly) ⇒ Promise
    • .patch(data, primaryKey, table) ⇒ Promise
    • .load(primaryKey, table) ⇒ Promise
    • .query(primaryKey, table, query) ⇒ Promise
    • .delete(primaryKey, table) ⇒ Promise
    • .getTotalCount(params, startCount) ⇒ Promise
    • .catchHandler(err) ⇒ Promise
  • static
    • .normalizeGroup(rawGroup, name) ⇒ Object
    • .normalizeCondition(rawCondition, name) ⇒ Object
    • .normalizeExpressionAttribute(rawValue, name) ⇒ Object
    • .normalizeDataValues(data) ⇒ Array
    • .buildUpdateExpression(attributes) ⇒ String
    • .buildConditionExpression(conditions, groupOperator) ⇒ String
    • .buildExpressionPlaceholders(attributes, substitutionChar) ⇒ Object
    • .valueIsEmpty(value) ⇒ boolean

new Exciter(options, [rejectOnFail])

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | AWS DynamoDB.DocumentClient constructor options. | | [rejectOnFail] | boolean | true | Whether DynamoDB operations should return a rejected promise if they fail. |

exciter.create(data, primaryKey, table) ⇒ Promise

Creates a record.

Kind: instance method of Exciter
Returns: Promise - Resolves when the document has been written to DynamoDB, rejects if there was an error.
See: put

| Param | Type | Description | | --- | --- | --- | | data | Object | Data to store in the given DynamoDB table. | | primaryKey | PrimaryKey | A PrimaryKey object containing partitionKey and sortKey key/value properties. NOTE: The values provided here will override properties of the same names contained in the data argument if they are present there. | | table | String | The table in which to save the document. |

exciter.update(data, primaryKey, table) ⇒ Promise

Updates an existing record accepting full or partial data.

This is a convenience method which simply proxies the patch() method.

Kind: instance method of Exciter
Returns: Promise - Resolves when the document has been written to DynamoDB, rejects if there was an error.
See: patch

| Param | Type | Description | | --- | --- | --- | | data | Object | Data to store in the given DynamoDB table. Each top-level property will become a top-level attribute in the DynamoDB table and will replace any existing top-level attribute with the same name entirely. We'd like to allow partial property updates which would recursively replace the structure provided while leaving any missing sub-properties untouched, but unfortunately we are prevented by this issue: https://forums.aws.amazon.com/thread.jspa?threadID=162907 | | primaryKey | PrimaryKey | A PrimaryKey object containing partitionKey and sortKey key/value properties. | | table | String | The table in which to save the document. |

exciter.put(data, primaryKey, table, createOnly) ⇒ Promise

Creates or entirely replaces an existing record.

Kind: instance method of Exciter
Returns: Promise - Resolves when the document has been written to DynamoDB, rejects if there was an error.

| Param | Type | Description | | --- | --- | --- | | data | Object | Data to store in the given DynamoDB table. | | primaryKey | PrimaryKey | A PrimaryKey object containing partitionKey and sortKey key/value properties. NOTE: The values provided here will override properties of the same names contained in the data argument if they are present there. | | table | String | The table in which to save the document. | | createOnly | Boolean | Whether the operation should succeed if a record with the same partition key value exists. |

exciter.patch(data, primaryKey, table) ⇒ Promise

Updates an existing record accepting full or partial data.

Creates a new record if none exists.

Kind: instance method of Exciter
Returns: Promise - Resolves when the document has been written to DynamoDB, rejects if there was an error.

| Param | Type | Description | | --- | --- | --- | | data | Object | Data to store in the given DynamoDB table. Each top-level property will become a top-level attribute in the DynamoDB table and will replace any existing top-level attribute with the same name entirely. We'd like to allow partial attribute updates which would recursively replace the structure provided while leaving any missing sub-properties untouched, but unfortunately we are prevented by this issue: https://forums.aws.amazon.com/thread.jspa?threadID=162907 | | primaryKey | PrimaryKey | A PrimaryKey object containing partitionKey and sortKey key/value properties. | | table | String | The table in which to save the document. |

exciter.load(primaryKey, table) ⇒ Promise

Retrieves documents from DynamoDB.

Kind: instance method of Exciter
Returns: Promise - Resolves when the documents have been retrieved from DynamoDB, rejects if there was an error retrieving the documents.

| Param | Type | Description | | --- | --- | --- | | primaryKey | PrimaryKey | A PrimaryKey object containing partitionKey and sortKey key/value properties. | | table | String | The table in which to save the document. |

exciter.query(primaryKey, table, query) ⇒ Promise

Query DynamoDB.

Kind: instance method of Exciter
Returns: Promise - A promise which resolves with the query result or rejects if there was an error.

| Param | Type | Default | Description | | --- | --- | --- | --- | | primaryKey | PrimaryKey | | A PrimaryKey object containing key value pairs for the DynamoDB partitionKey and optionally sortKey. | | table | String | | The table in which to query. | | query | Object | | An object which contains all the necessary information to query DynamoDB. | | query.index | String | | The index with which to query. By default, query and scan operations are performed against the table directly. | | query.rawFilters | Object | {} | A set of filtering operations keyed by name. | | query.rawFilters[].path | Mixed | | The path to the property to filter against. | | query.rawFilters[].value | Mixed | | The value of the property to filter against. | | query.rawFilters[].operator | String | | | | query.rawFilters[].memberOf | String | | | | query.rawFilters[].negate | Boolean | | | | query.limit | Integer | 10 | The number of results to return per page. | | query.pageForward | Boolean | true | Whether the query should be running in forward sort order. Passing false will result in reverse sort order. Defaults to true (forward sort order). | | query.sortAscending | Boolean | | Whether the sort should be in ascending order. If false, results will be sorted in descending order. Defaults to true. | | query.startKey | Object | String | | The primary key of the record AFTER which the query operation should begin. This is used for pagination (see "primaryKey" above). The startKey may also contain the string "last" which will return the last page of results as if you had paginated to the last page in the result set. This is useful since otherwise the startKey which would result in the last page is not known until you paginate all the way through the results. | | query.includeTotal | Object | false | Determines whether a total count should be included in the response. Setting this to true will cause a second parallel request to DynamoDB. DynamoDB does not provide total counts within a regular query response, so a separate request is necessary to retrieve that information. |

exciter.delete(primaryKey, table) ⇒ Promise

Formats data into DynamoDB documents and sends them to DynamoDB.

Kind: instance method of Exciter
Returns: Promise - Resolves when the documents have been written to DynamoDB, rejects if there was an error either opening the documents or writing to DynamoDB.

| Param | Type | Description | | --- | --- | --- | | primaryKey | PrimaryKey | A PrimaryKey object containing key value pairs for the DynamoDB partitionKey and sortKey. | | table | String | The table from which to delete the document. |

exciter.getTotalCount(params, startCount) ⇒ Promise

Gets the total count for a given query.

Kind: instance method of Exciter
Returns: Promise - Resolves with the total number of records which satisfy the given query.

| Param | Type | Default | Description | | --- | --- | --- | --- | | params | Object | | The params for the query for which we want to get a total count. These are the parameters which would be passed to DocumentClient.query(). | | startCount | Integer | 0 | The number from which to start counting. This is used when the result is too large to count with one request. |

exciter.catchHandler(err) ⇒ Promise

Helper to provide uniform handling of rejection behavior.

Kind: instance method of Exciter
Returns: Promise - A resolved promise if rejectOnFail is truthy. Otherwise, it passes errors up the chain by returning a rejected promise with the passed error.

| Param | Type | Description | | --- | --- | --- | | err | mixed | The rejected value. |

Exciter.normalizeGroup(rawGroup, name) ⇒ Object

Convert raw filter groups into a consistent format for use in condition expressions.

Kind: static method of Exciter
Returns: Object - The normalized group object. { name: conjunction: <AND|OR> }
Throws:

• Error Will throw an error if an unsuppored conjunction is used.

| Param | Type | Description | | --- | --- | --- | | rawGroup | Object | The raw group object to be normalized. | | name | String | The name of the group. |

Exciter.normalizeCondition(rawCondition, name) ⇒ Object

Convert raw filter conditions into a consistent format for use in condition expressions.

Kind: static method of Exciter
Returns: Object - The normalized condition object.
See: buildConditionExpression()

| Param | Type | Description | | --- | --- | --- | | rawCondition | Object | The raw condition object to be normalized. | | name | String | The name of the condition. Will be used as the path if none is provided. |

Exciter.normalizeExpressionAttribute(rawValue, name) ⇒ Object

Convert raw attribute values to a consistent format for use in building DynamoDB expressions.

Kind: static method of Exciter
Returns: Object - The normalized attribute object.
Throws:

• Error Will throw an error if the attribute is missing a name or value.

See: buildExpressionPlaceholders()

| Param | Type | Description | | --- | --- | --- | | rawValue | Mixed | The raw attribute object or value to be normalized. | | name | String | The name of the attribute. |

Exciter.normalizeDataValues(data) ⇒ Array

Nest property value under a value property. Ensures raw entity data can be processed by buildUpdateExpression

Kind: static method of Exciter
Returns: Array - An array of normalized values.
See

• normalizeExpressionAttribute()
• buildUpdateExpression()

| Param | Type | Description | | --- | --- | --- | | data | Object | The raw object to be normalized. |

Exciter.buildUpdateExpression(attributes) ⇒ String

Builds a DynamoDB update expression

Kind: static method of Exciter
Returns: String - A property escaped expression for udpating DynamoDB.

| Param | Type | Description | | --- | --- | --- | | attributes | Array | An array of data attributes to update on an entity in DynamoDB. |

Exciter.buildConditionExpression(conditions, groupOperator) ⇒ String

Builds a DynamoDB conditional expression.

Kind: static method of Exciter
Returns: String - A property escaped expression for querying DynamoDB.

| Param | Type | Description | | --- | --- | --- | | conditions | Array | A set of conditions from which to create a conditional expression. | | groupOperator | String | The logical operator which will join the conditions. Defaults to "AND". |

Exciter.buildExpressionPlaceholders(attributes, substitutionChar) ⇒ Object

Builds expression name and value placeholders from a set of attributes. See http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ExpressionPlaceholders.html

Kind: static method of Exciter
Returns: Object - A DynamoDB expression attribute values/names object.

| Param | Type | Description | | --- | --- | --- | | attributes | Array | An array of normalized expression attributes as returned by normalizeExpressionAttribute(). | | substitutionChar | String | What string to prepend to keys of the object. ex: # or : |

Exciter.valueIsEmpty(value) ⇒ boolean

Determines whether a value is empty according to DynamoDB.

DynamoDB does not allow us to store undefined, empty string, or empty array values. This function can be paired with a filter to skip empty values when writing to DynamoDB.

Kind: static method of Exciter
Returns: boolean - Whether or not the value is valid for DynamoDB storage.

| Param | Type | Description | | --- | --- | --- | | value | mixed | The value to validate. |

TypedArray : Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array

Array-like objects which provide a mechanism for accessing raw binary data.

Kind: global typedef

PrimaryKey : Object.<String, (String|Number|Buffer|File|Blob|ArrayBuffer|DataView|TypedArray)>

An object containing two properties. One for the partition/hash key and another for the sort/range key. The key names should always match your configuration on the DynamoDB table/index being operated on. The partition/hash key is always required. The sort/range key is required in write operations where the table/index uses a composite primary key, but is optional in every other case.

Kind: global typedef

Contributors

| | --- | --- | --- Luke | Peter Sieg | Flip