electrodb 1.4.6 → 1.6.0

package/CHANGELOG.md

@@ -98,10 +98,40 @@ All notable changes to this project will be documented in this file. Breaking ch
 ### Patched
 - Updates did not include composite attributes involved in primary index. Though these values cannot be changed, they should be `set` on update method calls in case the update results in an item insert. [[read more]](./README.md#updates-to-composite-attributes)
 
-## [1.4.5] = 2021-10-17
+## [1.4.5] - 2021-10-17
 ### Fixed
 - Improved .npmignore to remove playground oriented files, and created official directory to keep playground in sync with library changes.
 
-## [1.4.6] = 2021-10-20
+## [1.4.6] - 2021-10-20
 ### Added, Fixed
-- Adding Entity identifiers to all update operations. When primary index composite attributes were added in 1.4.4, entities were written properly but did not include the identifiers. This resulted in entities being written but not being readable without the query option `ignoreOwnership` being used.
+- Adding Entity identifiers to all update operations. When primary index composite attributes were added in 1.4.4, entities were written properly but did not include the identifiers. This resulted in entities being written but not being readable without the query option `ignoreOwnership` being used.
+
+## [1.4.7] - 2021-10-20
+### Changed
+- Using `add()` update mutation now resolves to `ADD #prop :prop` update expression instead of a `SET #prop = #prop + :prop`
+
+### Fixed
+- Fixed param naming conflict during updates, when map attribute shares a name with another (separate) attribute.
+
+## [1.4.8] - 2021-11-01
+### Fixed
+- Addressed issue#90 to flip batchGet's response tuple type definition.
+
+## [1.5.0] - 2021-11-07
+### Changed
+- Queries will now fully paginate all responses. Prior to this change, ElectroDB would only return items from a single ElectroDB query result. Now ElectroDB will paginate through all query results. This will impact both uses of entity queries and service collections. [[read more](./README.md#query-method)]
+- The query option `limit` has an extended meaning with the change to automatically paginate records on query. The option `limit` now represents a target for the number of items to return from DynamoDB. If this option is passed, Queries on entities and through collections will paginate DynamoDB until this limit is reached or all items for that query have been returned. [[read more](./README.md#query-options)]
+
+### Added
+- A new query option `pages` has been added to coincide with the change to automatically paginate all records when queried. The `pages` option sets a max number of pagination iterations ElectroDB will perform on a query. When this option is paired with `limit`, ElectroDB will respect the first condition reached. [[read more](./README.md#query-options)]
+
+## [1.6.0] - 2021-11-21
+### Added
+- Exporting TypeScript interfaces for `ElectroError` and `ElectroValidationError`
+- Errors thrown within an attribute's validate callback are now wrapped and accessible after being thrown. Prior to this change, only the `message` of the error thrown by a validation function was persisted back through to the user, now the error itself is also accessible. Reference the exported interface typedef for `ElectroValidationError` [here](./index.d.ts) to see the new properties available on a thrown validation error.
+
+### Changed
+- As a byproduct of enhancing validation errors, the format of message text on a validation error has changed. This could be breaking if your app had a hardcoded dependency on the exact text of a thrown validation error.
+
+### Fixed
+- For Set attributes, the callback functions `get`, `set`, and `validate` are now consistently given an Array of values. These functions would sometimes (incorrectly) be called with a DynamoDB DocClient Set.

package/README.md

@@ -107,11 +107,11 @@ tasks
   * [TypeScript Support](#typescript-support)
     + [TypeScript Services](#typescript-services)
   * [Join](#join)
-    - [Independent Models](#independent-models)
-    - [Joining Entity instances to a Service](#joining-entity-instances-to-a-service)
-    - [Joining models to a Service](#joining-models-to-a-service)
-    - [Joining Entities or Models with an alias](#joining-entities-or-models-with-an-alias)
-    - [Joining Entities at Service construction for TypeScript](#joining-entities-at-service-construction-for-typescript)
+      - [Independent Models](#independent-models)
+      - [Joining Entity instances to a Service](#joining-entity-instances-to-a-service)
+      - [Joining models to a Service](#joining-models-to-a-service)
+      - [Joining Entities or Models with an alias](#joining-entities-or-models-with-an-alias)
+      - [Joining Entities at Service construction for TypeScript](#joining-entities-at-service-construction-for-typescript)
   * [Model](#model)
     + [Model Properties](#model-properties)
     + [Service Options](#service-options)
@@ -125,7 +125,7 @@ tasks
       - [Set Attributes](#set-attributes)
       - [Attribute Getters and Setters](#attribute-getters-and-setters)
       - [Attribute Watching](#attribute-watching)
-        * [Attribute Watching: Watch All](#attribute-watching-watch-all)
+        * [Attribute Watching: Watch All](#attribute-watching--watch-all)
         * [Attribute Watching Examples](#attribute-watching-examples)
       - [Calculated Attributes](#calculated-attributes)
       - [Virtual Attributes](#virtual-attributes)
@@ -147,7 +147,7 @@ tasks
     + [Collection Queries vs Entity Queries](#collection-queries-vs-entity-queries)
     + [Collection Response Structure](#collection-response-structure)
   * [Sub-Collections](#sub-collections)
-    - [Sub-Collection Entities](#sub-collection-entities)
+      - [Sub-Collection Entities](#sub-collection-entities)
   * [Index and Collection Naming Conventions](#index-and-collection-naming-conventions)
     + [Index Naming Conventions](#index-naming-conventions)
   * [Collection Naming Conventions](#collection-naming-conventions)
@@ -163,12 +163,13 @@ tasks
     + [Multiple Where Clauses](#multiple-where-clauses)
   * [Parse](#parse)
 - [Building Queries](#building-queries)
-  + [Using composite attributes to make hierarchical keys](#using-composite-attributes-to-make-hierarchical-keys)
-    - [Shopping Mall Stores](#shopping-mall-stores)
-  + [Query App Records](#query-app-records)
-    - [Partition Key Composite Attributes](#partition-key-composite-attributes)
-  + [Sort Key Operations](#sort-key-operations)
+    + [Using composite attributes to make hierarchical keys](#using-composite-attributes-to-make-hierarchical-keys)
+      - [Shopping Mall Stores](#shopping-mall-stores)
+    + [Query App Records](#query-app-records)
+      - [Partition Key Composite Attributes](#partition-key-composite-attributes)
+    + [Sort Key Operations](#sort-key-operations)
   * [Query Chains](#query-chains)
+    + [Query Method](#query-method)
     + [Get Method](#get-method)
     + [Batch Get](#batch-get)
     + [Delete Method](#delete-method)
@@ -177,14 +178,14 @@ tasks
     + [Batch Write Put Records](#batch-write-put-records)
     + [Update Record](#update-record)
       - [Updates to Composite Attributes](#updates-to-composite-attributes)
-      - [Update Method: Set](#update-method-set)
-      - [Update Method: Remove](#update-method-remove)
-      - [Update Method: Add](#update-method-add)
-      - [Update Method: Subtract](#update-method-subtract)
-      - [Update Method: Append](#update-method-append)
-      - [Update Method: Delete](#update-method-delete)
-      - [Update Method: Data](#update-method-data)
-    + [Update Method: Complex Data Types](#update-method-complex-data-types)
+      - [Update Method: Set](#update-method--set)
+      - [Update Method: Remove](#update-method--remove)
+      - [Update Method: Add](#update-method--add)
+      - [Update Method: Subtract](#update-method--subtract)
+      - [Update Method: Append](#update-method--append)
+      - [Update Method: Delete](#update-method--delete)
+      - [Update Method: Data](#update-method--data)
+    + [Update Method: Complex Data Types](#update-method--complex-data-types)
     + [Scan Records](#scan-records)
     + [Remove Method](#remove-method)
     + [Patch Record](#patch-record)
@@ -204,30 +205,33 @@ tasks
         * [Pagination Example](#pagination-example)
   * [Query Examples](#query-examples)
   * [Query Options](#query-options)
-- [Errors:](#errors)
-  + [No Client Defined On Model](#no-client-defined-on-model)
-  + [Invalid Identifier](#invalid-identifier)
-  + [Invalid Key Composite Attribute Template](#invalid-key-composite-attribute-template)
-  + [Duplicate Indexes](#duplicate-indexes)
-  + [Collection Without An SK](#collection-without-an-sk)
-  + [Duplicate Collections](#duplicate-collections)
-  + [Missing Primary Index](#missing-primary-index)
-  + [Invalid Attribute Definition](#invalid-attribute-definition)
-  + [Invalid Model](#invalid-model)
-  + [Invalid Options](#invalid-options)
-  + [Duplicate Index Fields](#duplicate-index-fields)
-  + [Duplicate Index Composite Attributes](#duplicate-index-composite-attributes)
-  + [Incompatible Key Composite Attribute Template](#incompatible-key-composite-attribute-template)
-  + [Invalid Index With Attribute Name](#invalid-index-with-attribute-name)
-  + [Invalid Collection on Index With Attribute Field Names](#invalid-collection-on-index-with-attribute-field-names)
-  + [Missing Composite Attributes](#missing-composite-attributes)
-  + [Missing Table](#missing-table)
-  + [Invalid Concurrency Option](#invalid-concurrency-option)
-  + [aws-error](#aws-error)
-  + [Unknown Errors](#unknown-errors)
-  + [Invalid Last Evaluated Key](#invalid-last-evaluated-key)
-  + [No Owner For Pager](#no-owner-for-pager)
-  + [Pager Not Unique](#pager-not-unique)
+- [Errors:](#errors-)
+    + [No Client Defined On Model](#no-client-defined-on-model)
+    + [Invalid Identifier](#invalid-identifier)
+    + [Invalid Key Composite Attribute Template](#invalid-key-composite-attribute-template)
+    + [Duplicate Indexes](#duplicate-indexes)
+    + [Collection Without An SK](#collection-without-an-sk)
+    + [Duplicate Collections](#duplicate-collections)
+    + [Missing Primary Index](#missing-primary-index)
+    + [Invalid Attribute Definition](#invalid-attribute-definition)
+    + [Invalid Model](#invalid-model)
+    + [Invalid Options](#invalid-options)
+    + [Duplicate Index Fields](#duplicate-index-fields)
+    + [Duplicate Index Composite Attributes](#duplicate-index-composite-attributes)
+    + [Incompatible Key Composite Attribute Template](#incompatible-key-composite-attribute-template)
+    + [Invalid Index With Attribute Name](#invalid-index-with-attribute-name)
+    + [Invalid Collection on Index With Attribute Field Names](#invalid-collection-on-index-with-attribute-field-names)
+    + [Missing Composite Attributes](#missing-composite-attributes)
+    + [Missing Table](#missing-table)
+    + [Invalid Concurrency Option](#invalid-concurrency-option)
+    + [Invalid Pages Option](#invalid-pages-option)
+    + [Invalid Limit Option](#invalid-limit-option)
+    + [Invalid Attribute](#invalid-attribute)
+    + [AWS Error](#aws-error)
+    + [Unknown Errors](#unknown-errors)
+    + [Invalid Last Evaluated Key](#invalid-last-evaluated-key)
+    + [No Owner For Pager](#no-owner-for-pager)
+    + [Pager Not Unique](#pager-not-unique)
 - [Examples](#examples)
   * [Employee App](#employee-app)
     + [Employee App Requirements](#employee-app-requirements)
@@ -1564,9 +1568,11 @@ name: "your_item_name"
 ## Collections
 A Collection is a grouping of Entities with the same Partition Key and allows you to make efficient query across multiple entities. If your background is SQL, imagine Partition Keys as Foreign Keys, a Collection represents a View with multiple joined Entities.
 
+> _NOTE: ElectroDB Collections use DynamoDB queries to retrieve results. One query is made to retrieve results for all Entities (the benefits of single table design), however like the [query method](#query-method), ElectroDB will paginate through all results for a given query._
+
 Collections are defined on an Index, and the name of the collection should represent what the query would return as a pseudo `Entity`. Additionally, Collection names must be unique across a `Service`.
 
-> **Note**: A `collection` name should be unique to a single common index across entities.
+> _NOTE: A `collection` name should be unique to a single common index across entities._
 
 ```javascript
 const DynamoDB = require("aws-sdk/clients/dynamodb");
@@ -2600,6 +2606,10 @@ Option            | Default | Notes
 # Building Queries
 > For hands-on learners: the following example can be followed along with **and** executed on runkit: https://runkit.com/tywalch/electrodb-building-queries
 
+ElectroDB queries use DynamoDB's `query` method to find records based on your table's indexes.
+
+> _NOTE: By default, ElectroDB will paginate through all items that match your query. To limit the number of items ElectroDB will retrieve, read more about the [Query Options](#query-options) `pages` and `limit`, or use the ElectroDB [Pagination API](#page) for fine-grain pagination support._
+
 Forming a composite **Partition Key** and **Sort Key** is a critical step in planning **Access Patterns** in **DynamoDB**. When planning composite keys, it is crucial to consider the order in which they are *composed*.  As of the time of writing this documentation, **DynamoDB**  has the following constraints that should be taken into account when planning your **Access Patterns**:
 1. You must always supply the **Partition Key** in full for all queries to **DynamoDB**.
 2. You currently only have the following operators available on a **Sort Key**: `begins_with`, `between`, `>`, `>=`, `<`, `<=`, and `Equals`.
@@ -2806,6 +2816,12 @@ Queries in ***ElectroDB*** are built around the **Access Patterns** defined in t
 
 The methods: Get (`get`), Create (`put`), Update (`update`), and Delete (`delete`) **require* all composite attributes described in the Entities' primary `PK` and `SK`.
 
+### Query Method
+
+ElectroDB queries use DynamoDB's `query` method to find records based on your table's indexes. To read more about queries checkout the section [Building Queries](#building-queries)
+
+> _NOTE: By default, ElectroDB will paginate through all items that match your query. To limit the number of items ElectroDB will retrieve, read more about the [Query Options](#query-options) `pages` and `limit`, or use the ElectroDB [Pagination API](#page) for fine-grain pagination support._
+
 ### Get Method
 Provide all Table Index composite attributes in an object to the `get` method. In the event no record is found, a value of `null` will be returned.
 
@@ -4032,7 +4048,7 @@ let stores = MallStores.query
 
 ### Page
 
-> As of September 29th 2020 the `.page()` now returns the composite attributes that make up the `ExclusiveStartKey` instead of the `ExclusiveStartKey` itself. To get back only the `ExclusiveStartKey`, add the [query option](#query-options) `{pager: "raw"}` to your query options. If you treated this value opaquely no changes are needed, or if you used the `raw` flag.
+> _NOTE: By Default, ElectroDB queries will paginate through all results with the [`go()`](#building-queries) method. ElectroDB's `page()` method can be used to manually iterate through DynamoDB query results._
 
 The `page` method _ends_ a query chain, and asynchronously queries DynamoDB with the `client` provided in the model. Unlike the `.go()`, the `.page()` method returns a tuple.
 
@@ -4093,6 +4109,9 @@ let [pageTwo, moreStores] = await MallStores.query
 ```
 
 #### Service Pagination
+
+> _NOTE: By Default, ElectroDB will paginate through all results with the [`query()`](#building-queries) method. ElectroDB's `page()` method can be used to manually iterate through DynamoDB query results._
+
 Pagination with services is also possible. Similar to [Entity Pagination](#entity-pagination), calling the `.page()` method returns a `[pager, results]` tuple. Also, similar to pagination on Entities, the pager object returned by default is a deconstruction of the returned LastEvaluatedKey.
 
 #### Pager Query Options
@@ -4261,6 +4280,7 @@ By default, **ElectroDB** enables you to work with records as the names and prop
   response?: "default" | "none" | "all_old" | "updated_old" | "all_new" | "updated_new";
   ignoreOwnership?: boolean;
   limit?: number;
+  pages?: number;
 };
 ```
 
@@ -4276,7 +4296,8 @@ concurrent      | `1`                  | When performing batch operations, how m
 unprocessed     | `"item"`             | Used in batch processing to override ElectroDBs default behaviour to break apart DynamoDBs `Unprocessed` records into composite attributes. See more detail about this in the sections for [BatchGet](#batch-get), [BatchDelete](#batch-write-delete-records), and [BatchPut](#batch-write-put-records).
 response        | `"default"`          | Used as a convenience for applying the DynamoDB parameter `ReturnValues`. The options here are the same as the parameter values for the DocumentClient except lowercase. The `"none"` option will cause the method to return null and will bypass ElectroDB's response formatting -- useful if formatting performance is a concern.
 ignoreOwnership | `false`              | By default, **ElectroDB** interrogates items returned from a query for the presence of matching entity "identifiers". This helps to ensure other entities, or other versions of an entity, are filtered from your results. If you are using ElectroDB with an existing table/dataset you can turn off this feature by setting this property to `true`.
-limit           | _none_               | A convenience option for the query parameter `Limit`, used to specify the number of records to retrieve while performing a query.
+limit           | _none_               | A target for the number of items to return from DynamoDB. If this option is passed, Queries on entities and through collections will paginate DynamoDB until this limit is reached or all items for that query have been returned.
+pages           | ∞                    | How many DynamoDB pages should a query iterate through before stopping. By default ElectroDB paginate through all results for your query.
 
 # Errors:
 
@@ -4531,12 +4552,68 @@ Tables can be defined on the [Service Options](#service-options) object when you
 *Code: 2004*
 
 *Why this occurred:*
-When performing a bulk operation ([Batch Get](#batch-get), [Batch Delete Records](#batch-write-delete-records), [Batch Put Records](#batch-write-put-records)) you can pass a [Query Options](#query-options) called `concurrent`, which impacts how many batch requests can occur at the same time. Your value pass the test of both, `!isNaN(parseInt(value))` and `parseInt(value) > 0`.
+When performing a bulk operation ([Batch Get](#batch-get), [Batch Delete Records](#batch-write-delete-records), [Batch Put Records](#batch-write-put-records)) you can pass a [Query Options](#query-options) called `concurrent`, which impacts how many batch requests can occur at the same time. Your value should pass the test of both, `!isNaN(parseInt(value))` and `parseInt(value) > 0`.
 
 *What to do about it:*   
-Expect this error only if you're providing a concurrency value. Double-check the value you are providing is the value you expect to be passing, and that the value passes the tests listed above.
+Expect this error only if you're providing a `concurrency` option. Double-check the value you are providing is the value you expect to be passing, and that the value passes the tests listed above.
+
+### Invalid Pages Option
+*Code: 2005*
+
+*Why this occurred:*
+When performing a query [Query](#building-queries) you can pass a [Query Options](#query-options) called `pages`, which impacts how many DynamoDB pages a query should iterate through. Your value should pass the test of both, `!isNaN(parseInt(value))` and `parseInt(value) > 0`.
+
+*What to do about it:*
+Expect this error only if you're providing a `pages` option. Double-check the value you are providing is the value you expect to be passing, and that the value passes the tests listed above.
+
+### Invalid Limit Option
+*Code: 2006*
+
+*Why this occurred:*
+When performing a query [Query](#building-queries) you can pass a [Query Options](#query-options) called `limit`, which impacts how many DynamoDB items a query should return. Your value should pass the test of both, `!isNaN(parseInt(value))` and `parseInt(value) > 0`.
+
+*What to do about it:*
+Expect this error only if you're providing a `limit` option. Double-check the value you are providing is the value you expect to be passing, and that the value passes the tests listed above.
+
+### Invalid Attribute
+*Code: 3001*
+
+*Why this occurred:*
+The value received for a validation either failed type expectations (e.g. a "number" instead of a "string"), or the user provided "validate" callback on an attribute rejected a value.
+
+*What to do about it:*
+Examine the error itself for more precise detail on why the failure occurred. The error object itself should have a property called "fields" which contains an array of every attribute that failed validation, and a reason for each. If the failure originated from a "validate" callback, the originally thrown error will be accessible via the `cause` property the corresponding element within the fields array.1
+
+Below is the type definition for an ElectroValidationError:
+
+```typescript
+ElectroValidationError<T extends Error = Error> extends ElectroError {
+    readonly name: "ElectroValidationError"
+    readonly fields: ReadonlyArray<{
+        /**
+         * The json path to the attribute that had a validation error
+         */
+        readonly field: string;
+
+        /**
+         * A description of the validation error for that attribute
+         */
+        readonly reason: string;
+
+        /**
+         * Index of the value passed (present only in List attribute validation errors)
+         */
+        readonly index: number | undefined;
+
+        /**
+         * The error thrown from the attribute's validate callback (if applicable)
+         */
+        readonly cause: T | undefined;
+    }>
+}
+```
 
-### aws-error
+### AWS Error
 *Code: 4001*
 
 *Why this occurred:*
@@ -5462,4 +5539,3 @@ This change stems from the fact the `facets` is already a defined term in the Dy
 
 # Coming Soon
 - Default query options defined on the `model` to give more general control of interactions with the Entity.
-- Complex attributes (list, map, set)

package/index.d.ts

@@ -1,6 +1,45 @@
 declare const WhereSymbol: unique symbol;
 declare const UpdateDataSymbol: unique symbol;
 
+export interface ElectroError extends Error {
+    readonly name: 'ElectroError';
+    readonly code: number;
+    readonly date: number;
+    readonly isElectroError: boolean;
+    ref: {
+        readonly code: number;
+        readonly section: string;
+        readonly name: string;
+        readonly sym: unique symbol;
+    }
+}
+
+interface ElectroValidationErrorFieldReference<T extends Error = Error> {
+    /**
+     * The json path to the attribute that had a validation error
+     */
+    readonly field: string;
+
+    /**
+     * A description of the validation error for that attribute
+     */
+    readonly reason: string;
+
+    /**
+     * Index of the value passed (present only in List attribute validation errors)
+     */
+    readonly index: number | undefined;
+
+    /**
+     * The error thrown from the attribute's validate callback (if applicable)
+     */
+    readonly cause: T | undefined;
+}
+
+export interface ElectroValidationError<T extends Error = Error> extends ElectroError {
+    readonly fields: ReadonlyArray<ElectroValidationErrorFieldReference<T>>;
+}
+
 interface ReadOnlyAttribute {
     readonly readOnly: true;
 }
@@ -933,6 +972,7 @@ interface QueryOptions {
     includeKeys?: boolean;
     originalErr?: boolean;
     ignoreOwnership?: boolean;
+    pages?: number;
 }
 
 // subset of QueryOptions
@@ -1103,7 +1143,7 @@ export class Entity<A extends string, F extends A, C extends string, S extends S
     readonly schema: S;
     constructor(schema: S, config?: EntityConfiguration);
     get(key: AllTableIndexCompositeAttributes<A,F,C,S>): SingleRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S> | null>;
-    get(key: AllTableIndexCompositeAttributes<A,F,C,S>[]): BulkRecordOperationOptions<A,F,C,S, [AllTableIndexCompositeAttributes<A,F,C,S>[], ResponseItem<A,F,C,S>[]]>;
+    get(key: AllTableIndexCompositeAttributes<A,F,C,S>[]): BulkRecordOperationOptions<A,F,C,S, [Array<ResponseItem<A,F,C,S>>, Array<AllTableIndexCompositeAttributes<A,F,C,S>>]>;
     delete(key: AllTableIndexCompositeAttributes<A,F,C,S>): DeleteRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>;
     delete(key: AllTableIndexCompositeAttributes<A,F,C,S>[]): BulkRecordOperationOptions<A,F,C,S, AllTableIndexCompositeAttributes<A,F,C,S>[]>;
     remove(key: AllTableIndexCompositeAttributes<A,F,C,S>): DeleteRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrodb",
-  "version": "1.4.6",
+  "version": "1.6.0",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {
@@ -11,7 +11,8 @@
     "test-types": "node ./node_modules/tsd/dist/cli.js",
     "coverage": "nyc npm run test-all && nyc report --reporter=text-lcov | coveralls",
     "coverage-coveralls-local": "nyc npm run test-all-local && nyc report --reporter=text-lcov | coveralls",
-    "coverage-html-local": "nyc npm run test-all-local && nyc report --reporter=html"
+    "coverage-html-local": "nyc npm run test-all-local && nyc report --reporter=html",
+    "build:browser": "browserify playground/browser.js -o playground/bundle.js"
   },
   "repository": {
     "type": "git",
@@ -30,6 +31,7 @@
     "@types/node": "^15.6.0",
     "@types/uuid": "^8.3.0",
     "aws-sdk": "2.630.0",
+    "browserify": "^17.0.0",
     "chai": "4.2.0",
     "coveralls": "^3.1.0",
     "istanbul": "0.4.5",

package/src/entity.js

@@ -150,7 +150,8 @@ class Entity {
 				names: expressions.names || {},
 				values: expressions.values || {},
 				expression: expressions.expression || ""
-			}
+			},
+			_isCollectionQuery: true,
 		};
 
 		let index = this.model.translations.collections.fromCollectionToIndex[collection];
@@ -241,8 +242,10 @@ class Entity {
 					return await this.executeBulkWrite(parameters, config);
 				case MethodTypes.batchGet:
 					return await this.executeBulkGet(parameters, config);
+				case MethodTypes.query:
+					return await this.executeQuery(parameters, config)
 				default:
-					return await this.executeQuery(method, parameters, config);
+					return await this.executeOperation(method, parameters, config);
 			}
 		} catch (err) {
 			if (config.originalErr || stackTrace === undefined) {
@@ -324,7 +327,54 @@ class Entity {
 		return [resultsAll, unprocessedAll];
 	}
 
-	async executeQuery(method, parameters, config) {
+	async executeQuery(parameters, config = {}) {
+		let results = config._isCollectionQuery
+			? {}
+			: [];
+		let ExclusiveStartKey;
+		let pages = this._normalizePagesValue(config.pages);
+		let max = this._normalizeLimitValue(config.limit);
+		let iterations = 0;
+		let count = 0;
+		do {
+			let limit = max === undefined
+				? parameters.Limit
+				: max - count;
+			let response = await this._exec("query", {ExclusiveStartKey, ...parameters, Limit: limit});
+
+			ExclusiveStartKey = response.LastEvaluatedKey;
+
+			if (validations.isFunction(config.parse)) {
+				response = config.parse(config, response);
+			} else {
+				response = this.formatResponse(response, parameters.IndexName, config);
+			}
+
+			if (config.raw || config._isPagination) {
+				return response;
+			} else if (config._isCollectionQuery) {
+				for (const entity in response) {
+					if (max) {
+						count += response[entity].length;
+					}
+					results[entity] = results[entity] || [];
+					results[entity] = [...results[entity], ...response[entity]];
+				}
+			} else if (Array.isArray(response)) {
+				if (max) {
+					count += response.length;
+				}
+				results = [...results, ...response];
+			} else {
+				return response;
+			}
+
+			iterations++;
+		} while(ExclusiveStartKey && iterations < pages && (max === undefined || count < max));
+		return results;
+	}
+
+	async executeOperation(method, parameters, config) {
 		let response = await this._exec(method, parameters);
 		if (validations.isFunction(config.parse)) {
 			return config.parse(config, response);
@@ -566,6 +616,24 @@ class Entity {
 		return value;
 	}
 
+	_normalizePagesValue(value = Number.MAX_SAFE_INTEGER) {
+		value = parseInt(value);
+		if (isNaN(value) || value < 1) {
+			throw new e.ElectroError(e.ErrorCodes.InvalidPagesOption, "Query option 'pages' must be of type 'number' and greater than zero.");
+		}
+		return value;
+	}
+
+	_normalizeLimitValue(value) {
+		if (value !== undefined) {
+			value = parseInt(value);
+			if (isNaN(value) || value < 1) {
+				throw new e.ElectroError(e.ErrorCodes.InvalidLimitOption, "Query option 'limit' must be of type 'number' and greater than zero.");
+			}
+		}
+		return value;
+	}
+
 	_deconstructKeys(index, keyType, key, backupFacets = {}) {
 		if (typeof key !== "string" || key.length === 0) {
 			return null;
@@ -693,6 +761,8 @@ class Entity {
 			response: 'default',
 			ignoreOwnership: false,
 			_isPagination: false,
+			_isCollectionQuery: false,
+			pages: undefined,
 		};
 
 		config = options.reduce((config, option) => {
@@ -705,6 +775,14 @@ class Entity {
 				config.params.ReturnValues = FormatToReturnValues[format];
 			}
 
+			if (option.pages !== undefined) {
+				config.pages = option.pages;
+			}
+
+			if (option._isCollectionQuery === true) {
+				config._isCollectionQuery = true;
+			}
+
 			if (option.includeKeys === true) {
 				config.includeKeys = true;
 			}
@@ -727,7 +805,8 @@ class Entity {
 				config.unprocessed = UnprocessedTypes.raw;
 			}
 
-			if (!isNaN(option.limit)) {
+			if (option.limit !== undefined) {
+				config.limit = option.limit;
 				config.params.Limit = option.limit;
 			}
 

package/src/errors.js

@@ -151,6 +151,18 @@ const ErrorCodes = {
     name: "InvalidConcurrencyOption",
     sym: ErrorCode
   },
+  InvalidPagesOption: {
+    code: 2005,
+    section: "invalid-pages-option",
+    name: "InvalidPagesOption",
+    sym: ErrorCode,
+  },
+  InvalidLimitOption: {
+    code: 2006,
+    section: "invalid-limit-option",
+    name: "InvalidLimitOption",
+    sym: ErrorCode,
+  },
   InvalidAttribute: {
     code: 3001,
     section: "invalid-attribute",
@@ -195,28 +207,112 @@ const ErrorCodes = {
   },
 };
 
+function makeMessage(message, section) {
+  return `${message} - For more detail on this error reference: ${getHelpLink(section)}`
+}
+
 class ElectroError extends Error {
-  constructor(err, message) {
+  constructor(code, message) {
     super(message);
     let detail = ErrorCodes.UnknownError;
-    if (err && err.sym === ErrorCode) {
-      detail = err
+    if (code && code.sym === ErrorCode) {
+      detail = code
     }
-    this.message = `${message} - For more detail on this error reference: ${getHelpLink(detail.section)}`;
-
+    this._message = message;
+    // this.message = `${message} - For more detail on this error reference: ${getHelpLink(detail.section)}`;
+    this.message = makeMessage(message, detail.section);
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, ElectroError);
     }
 
     this.name = 'ElectroError';
-    this.ref = err;
+    this.ref = code;
     this.code = detail.code;
-    this.date = new Date();
+    this.date = Date.now();
     this.isElectroError = true;
   }
 }
 
+class ElectroValidationError extends ElectroError {
+  constructor(errors = []) {
+    const fields = [];
+    const messages = [];
+    for (let i = 0; i < errors.length; i++) {
+      const error = errors[i];
+      const message = error ? (error._message || error.message) : undefined;
+      messages.push(message);
+      if (error instanceof ElectroUserValidationError) {
+        fields.push({
+          field: error.field,
+          index: error.index,
+          reason: message,
+          cause: error.cause,
+          type: 'validation'
+        });
+      } else if (error instanceof ElectroAttributeValidationError) {
+        fields.push({
+          field: error.field,
+          index: error.index,
+          reason: message,
+          cause: error.cause || error, // error | undefined
+          type: 'validation'
+        });
+      } else if (message) {
+        fields.push({
+          field: '',
+          index: error.index,
+          reason: message,
+          cause: error !== undefined ? error.cause || error : undefined,
+          type: 'fatal'
+        });
+      }
+    }
+
+    const message = messages
+        .filter(message => typeof message === "string" && message.length)
+        .join(', ') || `Invalid value(s) provided`;
+
+    super(ErrorCodes.InvalidAttribute, message);
+    this.fields = fields;
+    this.name = "ElectroValidationError";
+  }
+}
+
+class ElectroUserValidationError extends ElectroError {
+  constructor(field, cause) {
+    let message;
+    let hasCause = false;
+    if (typeof cause === "string") {
+      message = cause;
+    } else if (cause !== undefined && typeof cause._message === "string" && cause._message.length) {
+      message = cause._message;
+      hasCause = true;
+    } else if (cause !== undefined && typeof cause.message === "string" && cause.message.length) {
+      message = cause.message;
+      hasCause = true;
+    } else {
+        message = "Invalid value provided";
+    }
+    super(ErrorCodes.InvalidAttribute, message);
+    this.field = field;
+    this.name = "ElectroUserValidationError";
+    if (hasCause) {
+      this.cause = cause;
+    }
+  }
+}
+
+class ElectroAttributeValidationError extends ElectroError {
+  constructor(field, reason) {
+    super(ErrorCodes.InvalidAttribute, reason);
+    this.field = field;
+  }
+}
+
 module.exports = {
+  ErrorCodes,
   ElectroError,
-  ErrorCodes
+  ElectroValidationError,
+  ElectroUserValidationError,
+  ElectroAttributeValidationError
 };

package/src/filters.js

@@ -39,7 +39,7 @@ class FilterFactory {
 									);
 								}
 							}
-							let expression = template(attribute, prop, ...attrValues);
+							let expression = template({}, attribute, prop, ...attrValues);
 							return expression.trim();
 						};
 					},

package/src/operations.js

@@ -4,7 +4,7 @@ const v = require("./util");
 
 const deleteOperations = {
     canNest: false,
-    template: function del(attr, path, value) {
+    template: function del(options, attr, path, value) {
         let operation = "";
         let expression = "";
         switch(attr.type) {
@@ -23,19 +23,19 @@ const deleteOperations = {
 const UpdateOperations = {
     name: {
         canNest: true,
-        template: function name(attr, path) {
+        template: function name(options, attr, path) {
             return path;
         }
     },
     value: {
         canNest: true,
-        template: function value(attr, path, value) {
+        template: function value(options, attr, path, value) {
             return value;
         }
     },
     append: {
         canNest: false,
-        template: function append(attr, path, value) {
+        template: function append(options, attr, path, value) {
             let operation = "";
             let expression = "";
             switch(attr.type) {
@@ -52,7 +52,7 @@ const UpdateOperations = {
     },
     add: {
         canNest: false,
-        template: function add(attr, path, value) {
+        template: function add(options, attr, path, value) {
             let operation = "";
             let expression = "";
             switch(attr.type) {
@@ -62,8 +62,13 @@ const UpdateOperations = {
                     expression = `${path} ${value}`;
                     break;
                 case AttributeTypes.number:
-                    operation = ItemOperations.set;
-                    expression = `${path} = ${path} + ${value}`;
+                    if (options.nestedValue) {
+                        operation = ItemOperations.set;
+                        expression = `${path} = ${path} + ${value}`;
+                    } else {
+                        operation = ItemOperations.add;
+                        expression = `${path} ${value}`;
+                    }
                     break;
                 default:
                     throw new Error(`Invalid Update Attribute Operation: "ADD" Operation can only be performed on attributes with type "number", "set", or "any".`);
@@ -73,7 +78,7 @@ const UpdateOperations = {
     },
     subtract: {
         canNest: false,
-        template: function subtract(attr, path, value) {
+        template: function subtract(options, attr, path, value) {
             let operation = "";
             let expression = "";
             switch(attr.type) {
@@ -91,7 +96,7 @@ const UpdateOperations = {
     },
     set: {
         canNest: false,
-        template: function set(attr, path, value) {
+        template: function set(options, attr, path, value) {
             let operation = "";
             let expression = "";
             switch(attr.type) {
@@ -114,7 +119,7 @@ const UpdateOperations = {
     },
     remove: {
         canNest: false,
-        template: function remove(attr, ...paths) {
+        template: function remove(options, attr, ...paths) {
             let operation = "";
             let expression = "";
             switch(attr.type) {
@@ -142,86 +147,86 @@ const UpdateOperations = {
 
 const FilterOperations = {
     ne: {
-        template: function eq(attr, name, value) {
+        template: function eq(options, attr, name, value) {
             return `${name} <> ${value}`;
         },
         strict: false,
     },
     eq: {
-        template: function eq(attr, name, value) {
+        template: function eq(options, attr, name, value) {
             return `${name} = ${value}`;
         },
         strict: false,
     },
     gt: {
-        template: function gt(attr, name, value) {
+        template: function gt(options, attr, name, value) {
             return `${name} > ${value}`;
         },
         strict: false
     },
     lt: {
-        template: function lt(attr, name, value) {
+        template: function lt(options, attr, name, value) {
             return `${name} < ${value}`;
         },
         strict: false
     },
     gte: {
-        template: function gte(attr, name, value) {
+        template: function gte(options, attr, name, value) {
             return `${name} >= ${value}`;
         },
         strict: false
     },
     lte: {
-        template: function lte(attr, name, value) {
+        template: function lte(options, attr, name, value) {
             return `${name} <= ${value}`;
         },
         strict: false
     },
     between: {
-        template: function between(attr, name, value1, value2) {
+        template: function between(options, attr, name, value1, value2) {
             return `(${name} between ${value1} and ${value2})`;
         },
         strict: false
     },
     begins: {
-        template: function begins(attr, name, value) {
+        template: function begins(options, attr, name, value) {
             return `begins_with(${name}, ${value})`;
         },
         strict: false
     },
     exists: {
-        template: function exists(attr, name) {
+        template: function exists(options, attr, name) {
             return `attribute_exists(${name})`;
         },
         strict: false
     },
     notExists: {
-        template: function notExists(attr, name) {
+        template: function notExists(options, attr, name) {
             return `attribute_not_exists(${name})`;
         },
         strict: false
     },
     contains: {
-        template: function contains(attr, name, value) {
+        template: function contains(options, attr, name, value) {
             return `contains(${name}, ${value})`;
         },
         strict: false
     },
     notContains: {
-        template: function notContains(attr, name, value) {
+        template: function notContains(options, attr, name, value) {
             return `not contains(${name}, ${value})`;
         },
         strict: false
     },
     value: {
-        template: function(attr, name, value) {
+        template: function(options, attr, name, value) {
             return value;
         },
         strict: false,
         canNest: true,
     },
     name: {
-        template: function(attr, name) {
+        template: function(options, attr, name) {
             return name;
         },
         strict: false,
@@ -230,7 +235,7 @@ const FilterOperations = {
 };
 
 class ExpressionState {
-    constructor({prefix, singleOccurrence} = {}) {
+    constructor({prefix} = {}) {
         this.names = {};
         this.values = {};
         this.paths = {};
@@ -238,13 +243,9 @@ class ExpressionState {
         this.impacted = {};
         this.expression = "";
         this.prefix = prefix || "";
-        this.singleOccurrence = singleOccurrence;
     }
 
     incrementName(name) {
-        if (this.singleOccurrence) {
-            return `${this.prefix}${0}`
-        }
         if (this.counts[name] === undefined) {
             this.counts[name] = 0;
         }
@@ -372,12 +373,14 @@ class AttributeOperationProxy {
                         if (property.__is_clause__ === AttributeProxySymbol) {
                             const {paths, root, target} = property();
                             const attributeValues = [];
+                            let hasNestedValue = false;
                             for (let value of values) {
                                 value = target.format(value);
                                 // template.length is to see if function takes value argument
-                                if (template.length > 2) {
+                                if (template.length > 3) {
                                     if (seen.has(value)) {
                                         attributeValues.push(value);
+                                        hasNestedValue = true;
                                     } else {
                                         let attributeValueName = builder.setValue(target.name, value);
                                         builder.setPath(paths.json, {value, name: attributeValueName});
@@ -386,7 +389,11 @@ class AttributeOperationProxy {
                                 }
                             }
 
-                            const formatted = template(target, paths.expression, ...attributeValues);
+                            const options = {
+                                nestedValue: hasNestedValue
+                            }
+
+                            const formatted = template(options, target, paths.expression, ...attributeValues);
                             builder.setImpacted(operation, paths.json);
                             if (canNest) {
                                 seen.add(paths.expression);

package/src/schema.js

@@ -289,7 +289,7 @@ class Attribute {
 
 	_makeCast(name, cast) {
 		if (cast !== undefined && !CastTypes.includes(cast)) {
-			throw new e.ElectroError(e.ErrorCodes.InvalidAttributeDefinition, `Invalid "cast" property for attribute: "${name}". Acceptable types include ${CastTypes.join(", ",)}`,
+			throw new e.ElectroError(e.ErrorCodes.InvalidAttributeDefinition, `Invalid "cast" property for attribute: "${name}". Acceptable types include ${CastTypes.join(", ")}`,
 		);
 		} else if (cast === AttributeTypes.string) {
 			return (val) => {
@@ -327,20 +327,34 @@ class Attribute {
 	_makeValidate(definition) {
 		if (typeof definition === "function") {
 			return (val) => {
-				let reason = definition(val);
-				return [!reason, reason || ""];
+				try {
+					let reason = definition(val);
+					const isValid = !reason;
+					if (isValid) {
+						return [isValid, []];
+					} else if (typeof reason === "boolean") {
+						return [isValid, [new e.ElectroUserValidationError(this.path, "Invalid value provided")]];
+					} else {
+						return [isValid, [new e.ElectroUserValidationError(this.path, reason)]];
+					}
+				} catch(err) {
+					return [false, [new e.ElectroUserValidationError(this.path, err)]];
+				}
 			};
 		} else if (definition instanceof RegExp) {
 			return (val) => {
 				if (val === undefined) {
-					return [true, ""];
+					return [true, []];
 				}
 				let isValid = definition.test(val);
-				let reason = isValid ? "" : `Invalid value for attribute "${this.path}": Failed model defined regex`;
+				let reason = [];
+				if (!isValid) {
+					reason.push(new e.ElectroUserValidationError(this.path, `Invalid value for attribute "${this.path}": Failed model defined regex`));
+				}
 				return [isValid, reason];
 			};
 		} else {
-			return (val) => [true, ""];
+			return () => [true, []];
 		}
 	}
 
@@ -385,15 +399,19 @@ class Attribute {
 
 	_isType(value) {
 		if (value === undefined) {
-			return [!this.required, this.required ? `Invalid value type at entity path: "${this.path}". Value is required.` : ""];
+			let reason = [];
+			if (this.required) {
+				reason.push(new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Value is required.`));
+			}
+			return [!this.required, reason];
 		}
 		let isTyped = false;
-		let reason = "";
+		let reason = [];
 		switch (this.type) {
 			case AttributeTypes.enum:
 				isTyped = this.enumArray.includes(value);
 				if (!isTyped) {
-					reason = `Invalid value type at entity path: "${this.path}". Value not found in set of acceptable values: ${u.commaSeparatedString(this.enumArray)}`;
+					reason.push(new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Value not found in set of acceptable values: ${u.commaSeparatedString(this.enumArray)}`));
 				}
 				break;
 			case AttributeTypes.any:
@@ -405,7 +423,7 @@ class Attribute {
 			default:
 				isTyped = typeof value === this.type;
 				if (!isTyped) {
-					reason = `Invalid value type at entity path: "${this.path}". Received value of type "${typeof value}", expected value of type "${this.type}"`;
+					reason.push(new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Received value of type "${typeof value}", expected value of type "${this.type}"`));
 				}
 				break;
 		}
@@ -414,12 +432,12 @@ class Attribute {
 
 	isValid(value) {
 		try {
-			let [isTyped, typeError] = this._isType(value);
-			let [isValid, validationError] = this.validate(value);
-			let reason = [typeError, validationError].filter(Boolean).join(", ");
-			return [isTyped && isValid, reason];
+			let [isTyped, typeErrorReason] = this._isType(value);
+			let [isValid, validationError] = isTyped ? this.validate(value) : [false, []];
+			let errors = [...typeErrorReason, ...validationError].filter(value => value !== undefined);
+			return [isTyped && isValid, errors];
 		} catch (err) {
-			return [false, err.message];
+			return [false, [err]];
 		}
 	}
 
@@ -433,10 +451,9 @@ class Attribute {
 
 	getValidate(value) {
 		value = this.val(value);
-		let [isValid, validationError] = this.isValid(value);
+		let [isValid, validationErrors] = this.isValid(value);
 		if (!isValid) {
-			// todo: #electroerror
-			throw new Error(validationError);
+			throw new e.ElectroValidationError(validationErrors);
 		}
 		return value;
 	}
@@ -509,13 +526,17 @@ class MapAttribute extends Attribute {
 
 	_isType(value) {
 		if (value === undefined) {
-			return [!this.required, this.required ? `Invalid value type at entity path: "${this.path}". Value is required.` : ""];
+			let reason = [];
+			if (this.required) {
+				reason.push(new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Value is required.`));
+			}
+			return [!this.required, reason];
 		}
 		const valueType = getValueType(value);
 		if (valueType !== ValueTypes.object) {
-			return [false, `Invalid value type at entity path "${this.path}. Received value of type "${valueType}", expected value of type "object"`];
+			return [false, [new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path "${this.path}. Received value of type "${valueType}", expected value of type "object"`)]];
 		}
-		let reason = "";
+		let reason = [];
 		const [childrenAreValid, childErrors] = this._validateChildren(value);
 		if (!childrenAreValid) {
 			reason = childErrors;
@@ -526,24 +547,24 @@ class MapAttribute extends Attribute {
 	_validateChildren(value) {
 		const valueType = getValueType(value);
 		const attributes = this.properties.attributes;
-		const errors = [];
+		let errors = [];
 		if (valueType === ValueTypes.object) {
 			for (const child of Object.keys(attributes)) {
-				const [isValid, errorMessages] = attributes[child].isValid(value === undefined ? value : value[child])
+				const [isValid, errorValues] = attributes[child].isValid(value === undefined ? value : value[child])
 				if (!isValid) {
-					errors.push(errorMessages);
+					errors = [...errors, ...errorValues]
 				}
 			}
 		} else if (valueType !== ValueTypes.object) {
 			errors.push(
-				`Invalid value type at entity path: "${this.path}". Expected value to be an object to fulfill attribute type "${this.type}"`
+				new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Expected value to be an object to fulfill attribute type "${this.type}"`)
 			);
 		} else if (this.properties.hasRequiredAttributes) {
 			errors.push(
-				`Invalid value type at entity path: "${this.path}". Map attribute requires at least the properties ${u.commaSeparatedString(Object.keys(attributes))}`
+				new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Map attribute requires at least the properties ${u.commaSeparatedString(Object.keys(attributes))}`)
 			);
 		}
-		return [errors.length === 0, errors.filter(Boolean).join(", ")];
+		return [errors.length === 0, errors];
 	}
 
 	val(value) {
@@ -560,7 +581,7 @@ class MapAttribute extends Attribute {
 		} else if (value && valueType !== "object" && Object.keys(value).length === 0) {
 			return getValue(value);
 		} else if (valueType !== "object") {
-			throw new Error(`Invalid value type at entity path: "${this.path}". Expected value to be an object to fulfill attribute type "${this.type}"`);
+			throw new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Expected value to be an object to fulfill attribute type "${this.type}"`);
 		}
 
 		const data = {};
@@ -643,24 +664,29 @@ class ListAttribute extends Attribute {
 	}
 
 	_validateArrayValue(value) {
+		const reason = [];
 		const valueType = getValueType(value);
 		if (value !== undefined && valueType !== ValueTypes.array) {
-			return [false, `Invalid value type at entity path "${this.path}. Received value of type "${valueType}", expected value of type "array"`];
+			return [false, [new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path "${this.path}. Received value of type "${valueType}", expected value of type "array"`)]];
 		} else {
-			return [true, ""];
+			return [true, []];
 		}
 	}
 
 	_isType(value) {
 		if (value === undefined) {
-			return [!this.required, this.required ? `Invalid value type at entity path: "${this.path}". Value is required.` : ""];
+			let reason = [];
+			if (this.required) {
+				reason.push(new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Value is required.`));
+			}
+			return [!this.required, reason];
 		}
 
 		const [isValidArray, errors] = this._validateArrayValue(value);
 		if (!isValidArray) {
 			return [isValidArray, errors];
 		}
-		let reason = "";
+		let reason = [];
 		const [childrenAreValid, childErrors] = this._validateChildren(value);
 		if (!childrenAreValid) {
 			reason = childErrors;
@@ -673,17 +699,22 @@ class ListAttribute extends Attribute {
 		const errors = [];
 		if (valueType === ValueTypes.array) {
 			for (const i in value) {
-				const [isValid, errorMessages] = this.items.isValid(value[i]);
+				const [isValid, errorValues] = this.items.isValid(value[i]);
 				if (!isValid) {
-					errors.push(errorMessages + ` at index "${i}"`);
+					for (const err of errorValues) {
+						if (err instanceof e.ElectroAttributeValidationError || err instanceof e.ElectroUserValidationError) {
+							err.index = parseInt(i);
+						}
+						errors.push(err);
+					}
 				}
 			}
 		} else {
 			errors.push(
-				`Invalid value type at entity path: "${this.path}". Expected value to be an Array to fulfill attribute type "${this.type}"`
+				new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Expected value to be an Array to fulfill attribute type "${this.type}"`)
 			);
 		}
-		return [errors.length === 0, errors.filter(Boolean).join(", ")];
+		return [errors.length === 0, errors];
 	}
 
 	val(value) {
@@ -700,7 +731,7 @@ class ListAttribute extends Attribute {
 		} else if (Array.isArray(value) && value.length === 0) {
 			return value;
 		} else if (!Array.isArray(value)) {
-			throw new Error(`Invalid value type at entity path "${this.path}. Received value of type "${getValueType(value)}", expected value of type "array"`);
+			throw new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path "${this.path}. Received value of type "${getValueType(value)}", expected value of type "array"`);
 		}
 
 		const data = [];
@@ -731,6 +762,20 @@ class SetAttribute extends Attribute {
 		this.items = items;
 		this.get = this._makeGet(definition.get, items);
 		this.set = this._makeSet(definition.set, items);
+		this.validate = this._makeSetValidate(definition);
+	}
+
+	_makeSetValidate(definition) {
+		const validate = this._makeValidate(definition.validate);
+		return (value) => {
+			if (Array.isArray(value)) {
+				return validate([...value]);
+			} else if (value && value.wrapperName === 'Set') {
+				return validate([...value.values])
+			} else {
+				return validate(value);
+			}
+		}
 	}
 
 	fromDDBSet(value) {
@@ -768,7 +813,7 @@ class SetAttribute extends Attribute {
 				return this._createDDBSet(value);
 			}
 			default:
-				throw new Error(`Invalid attribute value supplied to "set" attribute "${this.path}". Received value of type "${valueType}". Set values must be supplied as either Arrays, native JavaScript Set objects, DocumentClient Set objects, strings, or numbers.`)
+				throw new e.ElectroAttributeValidationError(this.path, `Invalid attribute value supplied to "set" attribute "${this.path}". Received value of type "${valueType}". Set values must be supplied as either Arrays, native JavaScript Set objects, DocumentClient Set objects, strings, or numbers.`)
 		}
 
 	}
@@ -795,7 +840,9 @@ class SetAttribute extends Attribute {
 		this._checkGetSet(set, "set");
 		const setter = set || ((attr) => attr);
 		return (values, siblings) => {
-			const results = setter(values, siblings);
+			const results = values && values.wrapperName === 'Set'
+				? setter(values.values, siblings)
+				: setter(values, siblings)
 			if (results !== undefined) {
 				return this.toDDBSet(results);
 			}
@@ -804,10 +851,14 @@ class SetAttribute extends Attribute {
 
 	_isType(value) {
 		if (value === undefined) {
-			return [!this.required, this.required ? `Invalid value type at entity path: "${this.path}". Value is required.` : ""];
+			const reason = [];
+			if (this.required) {
+				reason.push(new e.ElectroAttributeValidationError(this.path, `Invalid value type at entity path: "${this.path}". Value is required.`));
+			}
+			return [!this.required, reason];
 		}
 
-		let reason = "";
+		let reason = [];
 		const [childrenAreValid, childErrors] = this._validateChildren(value);
 		if (!childrenAreValid) {
 			reason = childErrors;
@@ -817,7 +868,7 @@ class SetAttribute extends Attribute {
 
 	_validateChildren(value) {
 		const valueType = getValueType(value);
-		const errors = [];
+		let errors = [];
 		let arr = [];
 		if (valueType === ValueTypes.array) {
 			arr = value;
@@ -827,16 +878,16 @@ class SetAttribute extends Attribute {
 			arr = value.values;
 		} else {
 			errors.push(
-				`Invalid value type at attribute path: "${this.path}". Expected value to be an Expected value to be an Array, native JavaScript Set objects, or DocumentClient Set objects to fulfill attribute type "${this.type}"`
+				new e.ElectroAttributeValidationError(this.path, `Invalid value type at attribute path: "${this.path}". Expected value to be an Expected value to be an Array, native JavaScript Set objects, or DocumentClient Set objects to fulfill attribute type "${this.type}"`)
 			)
 		}
 		for (const item of arr) {
-			const [isValid, errorMessage] = this.items.isValid(item);
+			const [isValid, errorValues] = this.items.isValid(item);
 			if (!isValid) {
-				errors.push(errorMessage);
+				errors = [...errors, ...errorValues];
 			}
 		}
-		return [errors.length === 0, errors.filter(Boolean).join(", ")];
+		return [errors.length === 0, errors];
 	}
 
 	val(value) {
@@ -1232,11 +1283,11 @@ class Schema {
 		for (const path of paths) {
 			const attribute = this.traverser.getPath(path);
 			if (!attribute) {
-				throw new Error(`Attribute "${path}" does not exist on model.`);
+				throw new e.ElectroAttributeValidationError(path, `Attribute "${path}" does not exist on model.`);
 			} else if (attribute.readOnly) {
-				throw new Error(`Attribute "${attribute.path}" is Read-Only and cannot be removed`);
+				throw new e.ElectroAttributeValidationError(attribute.path, `Attribute "${attribute.path}" is Read-Only and cannot be removed`);
 			} else if (attribute.required) {
-				throw new Error(`Attribute "${attribute.path}" is Required and cannot be removed`);
+				throw new e.ElectroAttributeValidationError(attribute.path, `Attribute "${attribute.path}" is Required and cannot be removed`);
 			}
 		}
 		return paths;
@@ -1251,7 +1302,7 @@ class Schema {
 			}
 			if (attribute.readOnly) {
 				// todo: #electroerror
-				throw new Error(`Attribute "${attribute.path}" is Read-Only and cannot be updated`);
+				throw new e.ElectroAttributeValidationError(attribute.path, `Attribute "${attribute.path}" is Read-Only and cannot be updated`);
 			} else {
 				record[path] = attribute.getValidate(value);
 			}

package/src/update.js

@@ -3,7 +3,7 @@ const {ItemOperations, BuilderTypes} = require("./types");
 
 class UpdateExpression extends ExpressionState {
     constructor(props = {}) {
-        super({...props, singleOccurrence: true});
+        super({...props});
         this.operations = {
             set: new Set(),
             remove: new Set(),

package/tsconfig.json

@@ -26,7 +26,7 @@
 
     /* Strict Type-Checking Options */
     "strict": true,                                 /* Enable all strict type-checking options. */
-     "noImplicitAny": true,                       /* Raise error on expressions and declarations with an implied 'any' type. */
+    "noImplicitAny": true,                       /* Raise error on expressions and declarations with an implied 'any' type. */
     // "strictNullChecks": true,                    /* Enable strict null checks. */
     // "strictFunctionTypes": true,                 /* Enable strict checking of function types. */
     // "strictBindCallApply": true,                 /* Enable strict 'bind', 'call', and 'apply' methods on functions. */