Merge branch 'v0.3'

Author: jeremydaly

.eslintignore

@@ -2,3 +2,4 @@ coverage
 node_modules
 __tests__
 *.test.js
+dist

.eslintrc.json

@@ -9,10 +9,6 @@
       "sourceType": "module"
   },
   "rules": {
-      "indent": [
-          "error",
-          2
-      ],
       "linebreak-style": [
           "error",
           "unix"

.gitignore

@@ -7,3 +7,6 @@ dump.rdb
 
 # coverage
 coverage
+
+# dist
+dist

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2020 Jeremy Daly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,15 +1,12 @@
-# DynamoDB Toolbox - v0.2
+# DynamoDB Toolbox
 
-[![Build Status](https://travis-ci.org/jeremydaly/dynamodb-toolbox.svg?branch=v0.2)](https://travis-ci.org/jeremydaly/dynamodb-toolbox)
+[![Build Status](https://travis-ci.org/jeremydaly/dynamodb-toolbox.svg?branch=master)](https://travis-ci.org/jeremydaly/dynamodb-toolbox)
 [![npm](https://img.shields.io/npm/v/dynamodb-toolbox.svg)](https://www.npmjs.com/package/dynamodb-toolbox)
 [![npm](https://img.shields.io/npm/l/dynamodb-toolbox.svg)](https://www.npmjs.com/package/dynamodb-toolbox)
 [![Coverage Status](https://coveralls.io/repos/github/jeremydaly/dynamodb-toolbox/badge.svg?branch=master)](https://coveralls.io/github/jeremydaly/dynamodb-toolbox?branch=master)
 
 ![dynamodb-toolbox](https://user-images.githubusercontent.com/2053544/69847647-b7910780-1245-11ea-8403-a35a0158f3aa.png)
 
-
-### **NOTE:** This project is in BETA. Please submit [issues/feedback](https://github.com/jeremydaly/dynamodb-toolbox/issues) or feel free to contact me on Twitter [@jeremy_daly](https://twitter.com/jeremy_daly).
-
 ## Single Table Designs have never been this easy!
 
 The **DynamoDB Toolbox** is a set of tools that makes it easy to work with [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) and the [DocumentClient](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/dynamodb-example-document-client.html). It's designed with **Single Tables** in mind, but works just as well with multiple tables. It lets you define your Entities (with typings and aliases) and map them to your DynamoDB tables. You can then **generate the API parameters** to `put`, `get`, `delete`, `update`, `query`, `scan`, `batchGet`, and `batchWrite` data by passing in JavaScript objects. The DynamoDB Toolbox will map aliases, validate and coerce types, and even write complex `UpdateExpression`s for you. 😉
@@ -146,12 +143,13 @@ If you like working with ORMs, that's great, and you should definitely give thes
 - **Projection Builder:** Specify which attributes and paths should be returned for each entity type, and automatically filter the results.
 - **Secondary Index Support:** Map your secondary indexes (GSIs and LSIs) to your table, and dynamically link your entity attributes.
 - **Batch Operations:** Full support for batch operations with a simpler interface to work with multiple entities and tables.
+- **Transactions:** Full support for transaction with a simpler interface to work with multiple entities and tables.
 - **Default Value Dependency Graphs:** Create dynamic attribute defaults by chaining other dynamic attribute defaults together.
+- **TypeScript Support:** v0.3 of this library was rewritten in TypeScript to provide strong typing support. Additional work is still required to support schema typing.
 
 ## Table of Contents
 
-- [DynamoDB Toolbox - v0.2](#dynamodb-toolbox---v02)
-    - [**NOTE:** This project is in BETA. Please submit issues/feedback or feel free to contact me on Twitter [@jeremy_daly](https://twitter.com/jeremy_daly).](#note-this-project-is-in-beta-please-submit-issuesfeedback-or-feel-free-to-contact-me-on-twitter-jeremy_daly)
+- [DynamoDB Toolbox](#dynamodb-toolbox)
   - [Single Table Designs have never been this easy!](#single-table-designs-have-never-been-this-easy)
   - [Installation and Basic Usage](#installation-and-basic-usage)
     - [This is *NOT* an ORM (at least it's not trying to be)](#this-is-not-an-orm-at-least-its-not-trying-to-be)
@@ -184,6 +182,11 @@ If you like working with ORMs, that's great, and you should definitely give thes
       - [Return Data](#return-data-2)
     - [batchWrite(items [,options] [,parameters])](#batchwriteitems-options-parameters)
       - [Return Data](#return-data-3)
+    - [transactGet(items [,options] [,parameters])](#transactgetitems-options-parameters)
+      - [Accessing items from multiple tables](#accessing-items-from-multiple-tables)
+      - [Return Data](#return-data-4)
+    - [transactWrite(items [,options] [,parameters])](#transactwriteitems-options-parameters)
+      - [Return Data](#return-data-5)
     - [parse(entity, input [,include])](#parseentity-input-include)
     - [get(entity, key [,options] [,parameters])](#getentity-key-options-parameters)
     - [delete(entity, key [,options] [,parameters])](#deleteentity-key-options-parameters)
@@ -572,7 +575,7 @@ The `scan()` method accepts two arguments. The first argument is an `options` ob
 | limit | `number` | The maximum number of items to retrieve per scan. (Limit) |
 | consistent | `boolean` | Enable a consistent read of the items (ConsistentRead) |
 | capacity | `string` | Return the amount of consumed capacity. One of either `none`, `total`, or `indexes` (ReturnConsumedCapacity) |
-| select | `string` | The attributes to be returned in the result. One of either `string` | `all_attributes`, `all_projected_attributes`, `specific_attributes`, or `count` (Select) |
+| select | `string` | The attributes to be returned in the result. One of either `all_attributes`, `all_projected_attributes`, `specific_attributes`, or `count` (Select) |
 | filters | `array` or `object` | A complex `object` or `array` of objects that specifies the scan's filter condition. See [Filters and Conditions](#filters-and-conditions). (FilterExpression) |
 | attributes | `array` or `object` | An `array` or array of complex `objects` that specify which attributes should be returned. See [Projection Expression](#projection-expression) below (ProjectionExpression) |
 | startKey | `object` | An object that contains the `partitionKey` and `sortKey` of the first item that this operation will evaluate. (ExclusiveStartKey) |
@@ -689,6 +692,82 @@ If you prefer to specify your own parameters, the optional third argument allows
 #### Return Data
 The data is returned with the same response syntax as the [DynamoDB BatchWriteItem API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html). If `autoExecute` and `autoParse` are enabled, a `.next()` method will be available on the returned object. Calling this function will call the `batchWrite` method again using the same options and passing any `UnprocessedItems` in as the `RequestItems`. This is a convenience method for retrying unprocessed keys.
 
+
+
+
+
+### transactGet(items [,options] [,parameters])
+
+> TransactGetItems is a synchronous operation that atomically retrieves multiple items from one or more tables (but not from indexes) in a single account and Region. 
+
+The `transactGet` method is a wrapper for the [DynamoDB TransactGetItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html). The DynamoDB Toolbox `transactGet` method supports all **TransactGetItem** API operations. The `transactGet` method returns a `Promise` and you must use `await` or `.then()` to retrieve the results. An alternative, synchronous method named `transactGetParams` can be used, but will only retrieve the generated parameters.
+
+The `transacthGet` method accepts three arguments. The first is an `array` of item keys to get. The DynamoDB Toolbox provides the `getTransaction` method on your entities to help you generate the proper key configuration. You can specify different entity types as well as entities from different tables, and this library will handle the proper payload construction.
+
+The optional second argument accepts an `options` object. The following options are all optional (corresponding TransactGetItems API references in parentheses):
+
+| Option | Type | Description |
+| -------- | :--: | ----------- |
+| capacity | `string` | Return the amount of consumed capacity. One of either `none`, `total`, or `indexes` (ReturnConsumedCapacity) |
+| execute | `boolean` | Enables/disables automatic execution of the DocumentClient method (default: *inherited from Table*) |
+| parse | `boolean` | Enables/disables automatic parsing of returned data when `autoExecute` evaluates to `true` (default: *inherited from Table*) |
+
+#### Accessing items from multiple tables
+Transaction items are atomic, so each `Get` contains the table name and key necessary to retrieve the item. The library will automatically handle adding the necessary information and will parse each entity automatically for you.
+
+```javascript
+const results = await MyTable.transactGet(
+  [
+    User.getTransaction({ family: 'Brady', name: 'Mike' }),
+    User.getTransaction({ family: 'Brady', name: 'Carol' }),
+    Pet.getTransaction({ family: 'Brady', name: 'Tiger' })
+  ], 
+  { capacity: 'total' }
+)
+```
+
+If you prefer to specify your own parameters, the optional third argument allows you to add custom parameters. [See Adding custom parameters and clauses](#adding-custom-parameters-and-clauses) for more information.
+
+#### Return Data
+The data is returned with the same response syntax as the [DynamoDB TransactGetItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html). If `autoExecute` and `autoParse` are enabled, any `Responses` data returned will be parsed into its corresponding Entity's aliases. Otherwise, the DocumentClient will return the unmarshalled data.
+
+### transactWrite(items [,options] [,parameters])
+
+> TransactWriteItems is a synchronous write operation that groups up to 25 action requests. The actions are completed atomically so that either all of them succeed, or all of them fail.
+
+The `transactWrite` method is a wrapper for the [DynamoDB TransactWriteItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html). The DynamoDB Toolbox `transactWrite` method supports all **TransactWriteItems** API operations. The `transactWrite` method returns a `Promise` and you must use `await` or `.then()` to retrieve the results. An alternative, synchronous method named `transactWriteParams` can be used, but will only retrieve the generated parameters.
+
+The `transactWrite` method accepts three arguments. The first is an `array` of item keys to either `put`, `delete`, `update` or `conditionCheck`. The DynamoDB Toolbox provides `putTransaction`,`deleteTransaction`, `updateTransaction`, and `conditionCheck` methods on your entities to help you generate the proper configuration for each item. You can specify different entity types as well as entities from different tables, and this library will handle the proper payload construction.
+
+The optional second argument accepts an `options` object. The following options are all optional (corresponding TransactWriteItems API references in parentheses):
+
+| Option | Type | Description |
+| -------- | :--: | ----------- |
+| capacity | `string` | Return the amount of consumed capacity. One of either `none`, `total`, or `indexes` (ReturnConsumedCapacity) |
+| metrics | `string` | Return item collection metrics. If set to `size`, the response includes statistics about item collections, if any, that were modified during the operation are returned in the response. One of either `none` or `size` (ReturnItemCollectionMetrics) |
+| token | `string` | Optional token to make the call idempotent, meaning that multiple identical calls have the same effect as one single call. (ClientRequestToken) |
+| execute | `boolean` | Enables/disables automatic execution of the DocumentClient method (default: *inherited from Entity*) |
+| parse | `boolean` | Enables/disables automatic parsing of returned data when `autoExecute` evaluates to `true` (default: *inherited from Entity*) |
+
+```javascript
+const result = await Default.transactWrite(
+  [
+    Pet.conditionCheck({ family: 'Brady', name: 'Tiger' }, { conditions: { attr: 'alive', eq: false } },
+    Pet.deleteTransaction({ family: 'Brady', name: 'Tiger' }),
+    User.putTransaction({ family: 'Brady', name: 'Carol', age: 40, roles: ['mother','wife'] }),
+    User.putTransaction({ family: 'Brady', name: 'Mike', age: 42, roles: ['father','husband'] })
+  ],{ 
+    capacity: 'total',
+    metrics: 'size',
+  }
+)
+```
+
+If you prefer to specify your own parameters, the optional third argument allows you to add custom parameters. [See Adding custom parameters and clauses](#adding-custom-parameters-and-clauses) for more information.
+
+#### Return Data
+The data is returned with the same response syntax as the [DynamoDB TransactWriteItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html).
+
 ### parse(entity, input [,include])
 
 Executes the `parse` method of the supplied `entity`. The `entity` must be a `string` that references the name of an Entity associated with the table. See the [Entity `parse` method](#parseinput-include) for additional parameters and behavior.
@@ -1182,4 +1261,4 @@ let results = await MyEntity.update(item, {}, {
 <IMG SRC="https://ad.doubleclick.net/ddm/trackimp/N1116303.3950900PODSEARCH.COM/B24770737.285235234;dc_trk_aid=479074825;dc_trk_cid=139488579;ord=[timestamp];dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=;gdpr=${GDPR};gdpr_consent=${GDPR_CONSENT_755}?" BORDER="0" HEIGHT="1" WIDTH="1" ALT="Advertisement">
 
 ## Contributions and Feedback
-Contributions, ideas and bug reports are welcome and greatly appreciated. Please add [issues](https://github.com/jeremydaly/dynamodb-toolbox/issues) for suggestions and bug reports or create a pull request. You can also contact me on Twitter: [@jeremy_daly](https://twitter.com/jeremy_daly).
+Contributions, ideas and bug reports are welcome and greatly appreciated. Please add [issues](https://github.com/jeremydaly/dynamodb-toolbox/issues) for suggestions and bug reports or create a pull request. You can also contact me on Twitter: [@jeremy_daly](https://twitter.com/jeremy_daly).