exciter v2.0.3

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)

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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()

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()

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()

Exciter.buildUpdateExpression(attributes) ⇒ String

Builds a DynamoDB update expression

Kind: static method of Exciter
Returns: String - A property escaped expression for udpating 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.

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.

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.

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