Merge 9b37adf into f347326

tywalch · Nov 22, 2021 · f92e354 · f92e354
2 parents f347326 + 9b37adf
commit f92e354
Show file tree

Hide file tree

Showing 13 changed files with 1,810 additions and 134 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -98,28 +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.
 
-## [1.4.7] = 2021-10-20
+## [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
+## [1.4.8] - 2021-11-01
 ### Fixed
 - Addressed issue#90 to flip batchGet's response tuple type definition.
 
-## [1.5.0] = 2021-11-07
+## [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
-- 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)]
+- 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.
diff --git a/README.md b/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,11 +163,11 @@ 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)
@@ -178,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)
@@ -205,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)
@@ -4572,7 +4575,45 @@ When performing a query [Query](#building-queries) you can pass a [Query Options
 *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.
 
-### aws-error
+### 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 Error {
+    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
 *Code: 4001*
 
 *Why this occurred:*

diff --git a/index.d.ts b/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: Date,
+    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;
 }

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "electrodb",
-  "version": "1.5.0",
+  "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": {