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

Exciter: Class representing a DynamoDB connection

Typedefs

TypedArray : Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array: Array-like objects which provide a mechanism for accessing raw binary data.
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.

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

npm

exciter

exciter

Usage

Classes

Typedefs