Miss any of our Open RFC calls?Watch the recordings here! »

exciter

2.0.3 • Public • Published

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

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
Luke Peter Sieg Flip

Keywords

none

Install

npm i exciter

DownloadsWeekly Downloads

15

Version

2.0.3

License

MIT

Last publish

Collaborators

  • avatar
  • avatar