electrodb 1.6.3 → 1.7.0

package/CHANGELOG.md

@@ -146,4 +146,8 @@ All notable changes to this project will be documented in this file. Breaking ch
 
 ## [1.6.3] - 2022-02-22
 ### Added
-- Add `data` update operation `ifNotExists` to allow for use of the UpdateExpression function "if_not_exists()".
+- Add `data` update operation `ifNotExists` to allow for use of the UpdateExpression function "if_not_exists()".
+
+## [1.7.0] - 2022-03-13
+### Added
+- New feature: "Listeners". Listeners open the door to some really cool tooling that was not possible because of how ElectroDB augments raw DynamoDB responses and did not provide easy access to raw DyanmoDB parameters.

package/README.md

@@ -305,9 +305,9 @@ npm install electrodb --save
 # Usage
 Require/import `Entity` and/or `Service` from `electrodb`:
 ```javascript  
-const {Entity, Service} = require("electrodb");
+const { Entity, Service } = require("electrodb");
 // or 
-import {Entity, Service} from "electrodb";
+import { Entity, Service } from "electrodb";
 ```
 
 # Entities and Services
@@ -325,9 +325,9 @@ In ***ElectroDB*** an `Entity` is represents a single business object. For examp
 
 Require or import `Entity` from `electrodb`:
 ```javascript  
-const {Entity} = require("electrodb");
+const { Entity } = require("electrodb");
 // or
-import {Entity} from "electrodb";
+import { Entity } from "electrodb";
 ```
 
 > When using TypeScript, for strong type checking, be sure to either add your model as an object literal to the Entity constructor or create your model using const assertions with the `as const` syntax.
@@ -337,9 +337,9 @@ In ***ElectroDB*** a `Service` represents a collection of related Entities. Serv
 
 Require:
 ```javascript  
-const {Service} = require("electrodb");
+const { Service } = require("electrodb");
 // or
-import {Service} from "electrodb";
+import { Service } from "electrodb";
 ```
 
 ## TypeScript Support
@@ -371,7 +371,7 @@ The property name you assign the entity will then be "alias", or name, you can r
 
 Services take an optional second parameter, similar to Entities, with a `client` and `table`. Using this constructor interface, the Service will utilize the values from those entities, if they were provided, or be passed values to override the `client` or `table` name on the individual entities.
 
-Not yet available for TypeScript, this pattern will also accept Models, or a mix of Entities and Models, in the same object literal format.
+While not yet typed, this pattern will also accept Models, or a mix of Entities and Models, in the same object literal format.
 
 ## Join
 When using JavaScript, use `join` to add [Entities](#entities) or [Models](#model) onto a Service.
@@ -4000,7 +4000,7 @@ TaskApp.collections
 ```
 
 ## Execute Queries
-Lastly, all query chains end with either a `.go()` or a `.params()` method invocation. These will either execute the query to DynamoDB (`.go()`) or return formatted parameters for use with the DynamoDB docClient (`.params()`).
+Lastly, all query chains end with either a `.go()`, `.params()`, or `page()` method invocation. These terminal methods will either execute the query to DynamoDB (`.go()`) or return formatted parameters for use with the DynamoDB docClient (`.params()`).
 
 Both `.params()` and `.go()` take a query configuration object which is detailed more in the section [Query Options](#query-options).
 
@@ -4287,6 +4287,8 @@ By default, **ElectroDB** enables you to work with records as the names and prop
   ignoreOwnership?: boolean;
   limit?: number;
   pages?: number;
+  logger?: (event) => void;
+  listeners Array<(event) => void>;
 };
 ```
 
@@ -4304,6 +4306,253 @@ response        | `"default"`          | Used as a convenience for applying the
 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 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.
+listeners       | `[]`                 | An array of callbacks that are invoked when [internal ElectroDB events](#events) occur.
+logger          | _none_               | A convenience option for a single event listener that semantically can be used for logging.
+
+# Events
+ElectroDB can be supplied with callbacks (see: [logging](#logging) and [listeners](#listeners) to learn how) to be invoked after certain request lifecycles. This can be useful for logging, analytics, expanding functionality, and more. The following are events currently supported by ElectroDB -- if you would like to see additional events feel free to create a github issue to discuss your concept/need!
+
+## Query Event
+The `query` event occurs when a query is made via the terminal methods [`go()`](#go) and [`page()`](#page). The event includes the exact parameters given to the provided client, the ElectroDB method used, and the ElectroDB configuration provided.
+
+*Type:*
+```typescript
+interface ElectroQueryEvent<P extends any = any> {
+    type: 'query';
+    method: "put" | "get" | "query" | "scan" | "update" | "delete" | "remove" | "patch" | "create" | "batchGet" | "batchWrite";
+    config: any;
+    params: P;
+}
+```
+
+*Example Input:*
+```typescript
+const prop1 = "22874c81-27c4-4264-92c3-b280aa79aa30";
+const prop2 = "366aade8-a7c0-4328-8e14-0331b185de4e";
+const prop3 = "3ec9ed0c-7497-4d05-bdb8-86c09a618047";
+
+entity.update({ prop1, prop2 })
+    .set({ prop3 })
+    .go()
+```
+
+*Example Output:*
+```json
+{
+    "type": "query",
+    "method": "update",
+    "params": {
+        "UpdateExpression": "SET #prop3 = :prop3_u0, #prop1 = :prop1_u0, #prop2 = :prop2_u0, #__edb_e__ = :__edb_e___u0, #__edb_v__ = :__edb_v___u0",
+        "ExpressionAttributeNames": {
+            "#prop3": "prop3",
+            "#prop1": "prop1",
+            "#prop2": "prop2",
+            "#__edb_e__": "__edb_e__",
+            "#__edb_v__": "__edb_v__"
+        },
+        "ExpressionAttributeValues": {
+            ":prop3_u0": "3ec9ed0c-7497-4d05-bdb8-86c09a618047",
+            ":prop1_u0": "22874c81-27c4-4264-92c3-b280aa79aa30",
+            ":prop2_u0": "366aade8-a7c0-4328-8e14-0331b185de4e",
+            ":__edb_e___u0": "entity",
+            ":__edb_v___u0": "1"
+        },
+        "TableName": "electro",
+        "Key": {
+            "pk": "$test#prop1_22874c81-27c4-4264-92c3-b280aa79aa30",
+            "sk": "$testcollection#entity_1#prop2_366aade8-a7c0-4328-8e14-0331b185de4e"
+        }
+    },
+    "config": {  }
+}
+```
+
+## Results Event
+The `results` event occurs when results are returned from DynamoDB. The event includes the exact results returned from the provided client, the ElectroDB method used, and the ElectroDB configuration provided. Note this event handles both failed (or thrown) results in addition to returned (or resolved) results.
+
+> **Pro-Tip:**
+> Use this event to hook into the DyanmoDB's [consumed capacity](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-ReturnConsumedCapacity) statistics to learn more about the impact and cost associated with your queries.
+
+*Type::*
+```typescript
+interface ElectroResultsEvent<R extends any = any> {
+    type: 'results';
+    method: "put" | "get" | "query" | "scan" | "update" | "delete" | "remove" | "patch" | "create" | "batchGet" | "batchWrite";
+    config: any;
+    results: R;
+    success: boolean;
+}
+```
+
+*Example Input:*
+```typescript
+const prop1 = "22874c81-27c4-4264-92c3-b280aa79aa30";
+const prop2 = "366aade8-a7c0-4328-8e14-0331b185de4e";
+
+entity.get({ prop1, prop2 }).go();
+```
+
+*Example Output:*
+```typescript
+{
+  "type": "results",
+  "method": "get",
+  "config": {  },
+  "success": true,
+  "results": {
+    "Item": {
+      "prop2": "366aade8-a7c0-4328-8e14-0331b185de4e",
+      "sk": "$testcollection#entity_1#prop2_366aade8-a7c0-4328-8e14-0331b185de4e",
+      "prop1": "22874c81-27c4-4264-92c3-b280aa79aa30",
+      "prop3": "3ec9ed0c-7497-4d05-bdb8-86c09a618047",
+      "__edb_e__": "entity",
+      "__edb_v__": "1",
+      "pk": "$test_1#prop1_22874c81-27c4-4264-92c3-b280aa79aa30"
+    }
+  }
+}
+```
+
+# Logging
+A logger callback function can be provided both the at the instantiation of an `Entity` or `Service` instance or as a [Query Option](#query-options). The property `logger` is implemented as a convenience property; under the hood ElectroDB uses this property identically to how it uses a [Listener](#listeners).
+
+*On the instantiation of an `Entity`:*
+```typescript
+import { DynamoDB } from 'aws-sdk';
+import {Entity, ElectroEvent} from 'electrodb';
+
+const table = "my_table_name";
+const client = new DynamoDB.DocumentClient();
+const logger = (event: ElectroEvent) => {
+    console.log(JSON.stringify(event, null, 4));
+}
+
+const task = new Entity({
+    // your model
+}, {
+    client,
+    table,
+    logger // <----- logger listener
+});
+```
+
+*On the instantiation of an `Service`:*
+```typescript
+import { DynamoDB } from 'aws-sdk';
+import {Entity, ElectroEvent} from 'electrodb';
+
+const table = "my_table_name";
+const client = new DynamoDB.DocumentClient();
+const logger = (event: ElectroEvent) => {
+    console.log(JSON.stringify(event, null, 4));
+}
+
+const task = new Entity({
+    // your model
+});
+
+const user = new Entity({
+    // your model
+});
+
+const service = new Service({ task, user }, {
+   client,
+   table,
+   logger // <----- logger listener
+});
+```
+
+*As a [Query Option](#query-options):*
+```typescript
+const logger = (event: ElectroEvent) => {
+    console.log(JSON.stringify(event, null, 4));
+}
+
+task.query
+    .assigned({ userId })
+    .go({ logger });
+```
+
+# Listeners
+ElectroDB can be supplied with callbacks (called "Listeners") to be invoked after certain request lifecycles. Unlike [Attribute Getters and Setters](#attribute-getters-and-setters), Listeners are implemented to react to events passively, not to modify values during the request lifecycle. Listeners can be useful for logging, analytics, expanding functionality, and more. Listeners can be provide both the at the instantiation of an `Entity` or `Service` instance or as a [Query Option](#query-options).
+
+> _NOTE: Listeners treated as synchronous callbacks and are not awaited. In the event that a callback throws an exception, ElectroDB will quietly catch and log the exception with `console.error` to prevent the exception from impacting your query.
+
+*On the instantiation of an `Entity`:*
+```typescript
+import { DynamoDB } from 'aws-sdk';
+import {Entity, ElectroEvent} from 'electrodb';
+
+const table = "my_table_name";
+const client = new DynamoDB.DocumentClient();
+const listener1 = (event: ElectroEvent) => {
+    // do work
+}
+
+const listener2 = (event: ElectroEvent) => {
+    // do work
+}
+
+const task = new Entity({
+    // your model
+}, {
+    client,
+    table,
+    listeners: [
+        listener1,
+        listener2, // <----- supports multiple listeners
+    ]
+});
+```
+
+*On the instantiation of an `Service`:*
+```typescript
+import { DynamoDB } from 'aws-sdk';
+import {Entity, ElectroEvent} from 'electrodb';
+
+const table = "my_table_name";
+const client = new DynamoDB.DocumentClient();
+
+const listener1 = (event: ElectroEvent) => {
+    // do work
+}
+
+const listener2 = (event: ElectroEvent) => {
+    // do work
+}
+
+const task = new Entity({
+    // your model
+});
+
+const user = new Entity({
+    // your model
+});
+
+const service = new Service({ task, user }, {
+    client,
+    table,
+    listeners: [
+        listener1,
+        listener2, // <----- supports multiple listeners
+    ]
+});
+```
+
+*As a [Query Option](#query-options):*
+```typescript
+const listener1 = (event: ElectroEvent) => {
+    // do work
+}
+
+const listener2 = (event: ElectroEvent) => {
+    // do work
+}
+
+task.query
+    .assigned({ userId })
+    .go({ listeners: [listener1, listener2] });
+```
 
 # Errors:
 
@@ -4311,7 +4560,7 @@ Error Code | Description
 :--------: | -------------------- 
 1000s      | Configuration Errors
 2000s      | Invalid Queries     
-3000s      | User Defined Errors 
+3000s      | User Defined Errors
 4000s      | DynamoDB Errors     
 5000s      | Unexpected Errors   
 

package/index.d.ts

@@ -974,6 +974,8 @@ interface QueryOptions {
     originalErr?: boolean;
     ignoreOwnership?: boolean;
     pages?: number;
+    listeners?: Array<EventListener>;
+    logger?: EventListener;
 }
 
 // subset of QueryOptions
@@ -1120,21 +1122,73 @@ type DocumentClient = {
     scan: DocumentClientMethod;
 }
 
+type ElectroDBMethodTypes = "put" | "get" | "query" | "scan" | "update" | "delete" | "remove" | "patch" | "create" | "batchGet" | "batchWrite";
+
+interface ElectroQueryEvent<P extends any = any> {
+    type: 'query';
+    method: ElectroDBMethodTypes;
+    config: any;
+    params: P;
+}
+
+interface ElectroResultsEvent<R extends any = any> {
+    type: 'results';
+    method: ElectroDBMethodTypes;
+    config: any;
+    results: R;
+    success: boolean;
+}
+
+type ElectroEvent = 
+    ElectroQueryEvent
+    | ElectroResultsEvent;
+
+type ElectroEventType = Pick<ElectroEvent, 'type'>;
+
+type EventListener = (event: ElectroEvent) => void;
+
+// todo: coming soon, more events!
+// | {
+//     name: "error";
+//     type: "configuration_error" | "invalid_query" | "dynamodb_client";
+//     message: string;
+//     details: ElectroError;
+// } | {
+//     name: "error";
+//     type: "user_defined";
+//     message: string;
+//     details: ElectroValidationError;
+// } | {
+//     name: "warn";
+//     type: "deprecation_warning" | "optimization_suggestion";
+//     message: string;
+//     details: any;
+// } | {
+//     name: "info";
+//     type: "client_updated" | "table_overwritten";
+//     message: string;
+//     details: any;
+// };
+
 type EntityConfiguration = {
     table?: string;
-    client?: DocumentClient
+    client?: DocumentClient;
+    listeners?: Array<EventListener>;
+    logger?: EventListener;
 };
 
 type ServiceConfiguration = {
     table?: string;
-    client?: DocumentClient
+    client?: DocumentClient;
+    listeners?: Array<EventListener>;
+    logger?: EventListener;
 };
 
 type ParseSingleInput = {
-        Item?: {[key: string]: any}
-    } | {
-        Attributes?: {[key: string]: any}
-    } | null
+    Item?: {[key: string]: any}
+} | {
+    Attributes?: {[key: string]: any}
+} | null;
 
 type ParseMultiInput = {
     Items?: {[key: string]: any}[]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrodb",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {

package/src/clauses.js

@@ -540,8 +540,9 @@ let clauses = {
 				if (!v.isStringHasLength(options.table) && !v.isStringHasLength(entity._getTableName())) {
 					throw new e.ElectroError(e.ErrorCodes.MissingTable, `Table name not defined. Table names must be either defined on the model, instance configuration, or as a query option.`);
 				}
+				const method = state.getMethod();
 				let results;
-				switch (state.getMethod()) {
+				switch (method) {
 					case MethodTypes.query:
 						results = entity._queryParams(state, options);
 						break;
@@ -556,7 +557,7 @@ let clauses = {
 						break;
 				}
 
-				if (state.getMethod() === MethodTypes.update && results.ExpressionAttributeValues && Object.keys(results.ExpressionAttributeValues).length === 0) {
+				if (method === MethodTypes.update && results.ExpressionAttributeValues && Object.keys(results.ExpressionAttributeValues).length === 0) {
 					// An update that only does a `remove` operation would result in an empty object
 					// todo: change the getValues() method to return undefined in this case (would potentially require a more generous refactor)
 					delete results.ExpressionAttributeValues;

package/src/entity.js

@@ -5,12 +5,17 @@ const { FilterFactory } = require("./filters");
 const { FilterOperations } = require("./operations");
 const { WhereFactory } = require("./where");
 const { clauses, ChainState } = require("./clauses");
+const {EventManager} = require('./events');
 const validations = require("./validations");
-const utilities = require("./util");
+const u = require("./util");
 const e = require("./errors");
 
 class Entity {
 	constructor(model, config = {}) {
+		this.eventManager = new EventManager({
+			listeners: config.listeners
+		});
+		this.eventManager.add(config.logger);
 		this._validateModel(model);
 		this.version = EntityVersions.v1;
 		this.config = config;
@@ -43,7 +48,7 @@ class Entity {
 
 	setIdentifier(type = "", identifier = "") {
 		if (!this.identifiers[type]) {
-			throw new e.ElectroError(e.ErrorCodes.InvalidIdentifier, `Invalid identifier type: "${type}". Valid identifiers include: ${utilities.commaSeparatedString(Object.keys(this.identifiers))}`);
+			throw new e.ElectroError(e.ErrorCodes.InvalidIdentifier, `Invalid identifier type: "${type}". Valid identifiers include: ${u.commaSeparatedString(Object.keys(this.identifiers))}`);
 		} else {
 			this.identifiers[type] = identifier;
 		}
@@ -252,9 +257,32 @@ class Entity {
 		}
 	}
 
-	async _exec(method, parameters) {
-		return this.client[method](parameters).promise()
+	async _exec(method, params, config = {}) {
+		const notifyQuery = () => {
+			this.eventManager.trigger({
+				type: "query",
+				method,
+				params,
+				config,
+			}, config.listeners);
+		};
+		const notifyResults = (results, success) => {
+			this.eventManager.trigger({
+				type: "results",
+				method,
+				config,
+				success,
+				results,
+			}, config.listeners);
+		}
+		return this.client[method](params).promise()
+			.then((results) => {
+				notifyQuery();
+				notifyResults(results, true);
+				return results;
+			})
 			.catch(err => {
+				notifyResults(err, false);
 				err.__isAWSError = true;
 				throw err;
 			});
@@ -266,10 +294,10 @@ class Entity {
 		}
 		let results = [];
 		let concurrent = this._normalizeConcurrencyValue(config.concurrent)
-		let concurrentOperations = utilities.batchItems(parameters, concurrent);
+		let concurrentOperations = u.batchItems(parameters, concurrent);
 		for (let operation of concurrentOperations) {
 			await Promise.all(operation.map(async params => {
-				let response = await this._exec(MethodTypes.batchWrite, params);
+				let response = await this._exec(MethodTypes.batchWrite, params, config);
 				if (validations.isFunction(config.parse)) {
 					let parsed = await config.parse(config, response);
 					if (parsed) {
@@ -292,13 +320,13 @@ class Entity {
 			parameters = [parameters];
 		}
 		let concurrent = this._normalizeConcurrencyValue(config.concurrent)
-		let concurrentOperations = utilities.batchItems(parameters, concurrent);
+		let concurrentOperations = u.batchItems(parameters, concurrent);
 
 		let resultsAll = [];
 		let unprocessedAll = [];
 		for (let operation of concurrentOperations) {
 			await Promise.all(operation.map(async params => {
-				let response = await this._exec(MethodTypes.batchGet, params);
+				let response = await this._exec(MethodTypes.batchGet, params, config);
 				if (validations.isFunction(config.parse)) {
 					resultsAll.push(await config.parse(config, response));
 					return;
@@ -328,7 +356,7 @@ class Entity {
 			let limit = max === undefined
 				? parameters.Limit
 				: max - count;
-			let response = await this._exec("query", {ExclusiveStartKey, ...parameters, Limit: limit});
+			let response = await this._exec("query", {ExclusiveStartKey, ...parameters, Limit: limit}, config);
 
 			ExclusiveStartKey = response.LastEvaluatedKey;
 
@@ -363,7 +391,7 @@ class Entity {
 	}
 
 	async executeOperation(method, parameters, config) {
-		let response = await this._exec(method, parameters);
+		let response = await this._exec(method, parameters, config);
 		if (validations.isFunction(config.parse)) {
 			return config.parse(config, response);
 		}
@@ -751,13 +779,14 @@ class Entity {
 			_isPagination: false,
 			_isCollectionQuery: false,
 			pages: undefined,
+			listeners: [],
 		};
 
 		config = options.reduce((config, option) => {
 			if (typeof option.response === 'string' && option.response.length) {
 				const format = 	ReturnValues[option.response];
 				if (format === undefined) {
-					throw new e.ElectroError(e.ErrorCodes.InvalidOptions, `Invalid value for query option "format" provided: "${option.format}". Allowed values include ${utilities.commaSeparatedString(Object.keys(ReturnValues))}.`);
+					throw new e.ElectroError(e.ErrorCodes.InvalidOptions, `Invalid value for query option "format" provided: "${option.format}". Allowed values include ${u.commaSeparatedString(Object.keys(ReturnValues))}.`);
 				}
 				config.response = format;
 				config.params.ReturnValues = FormatToReturnValues[format];
@@ -814,7 +843,7 @@ class Entity {
 				if (typeof Pager[option.pager] === "string") {
 					config.pager = option.pager;
 				} else {
-					throw new e.ElectroError(e.ErrorCodes.InvalidOptions, `Invalid value for option "pager" provided: "${option.pager}". Allowed values include ${utilities.commaSeparatedString(Object.keys(Pager))}.`);
+					throw new e.ElectroError(e.ErrorCodes.InvalidOptions, `Invalid value for option "pager" provided: "${option.pager}". Allowed values include ${u.commaSeparatedString(Object.keys(Pager))}.`);
 				}
 			}
 
@@ -822,7 +851,7 @@ class Entity {
 				if (typeof UnprocessedTypes[option.unprocessed] === "string") {
 					config.unproessed = UnprocessedTypes[option.unprocessed];
 				} else {
-					throw new e.ElectroError(e.ErrorCodes.InvalidOptions, `Invalid value for option "unprocessed" provided: "${option.unprocessed}". Allowed values include ${utilities.commaSeparatedString(Object.keys(UnprocessedTypes))}.`);
+					throw new e.ElectroError(e.ErrorCodes.InvalidOptions, `Invalid value for option "unprocessed" provided: "${option.unprocessed}". Allowed values include ${u.commaSeparatedString(Object.keys(UnprocessedTypes))}.`);
 				}
 			}
 
@@ -830,6 +859,20 @@ class Entity {
 				config.ignoreOwnership = option.ignoreOwnership;
 			}
 
+			if (option.listeners) {
+				if (Array.isArray(option.listeners)) {
+					config.listeners = config.listeners.concat(option.listeners);
+				}
+			}
+
+			if (option.logger) {
+				if (validations.isFunction(option.logger)) {
+					config.listeners.push(option.logger);
+				} else {
+					throw new e.ElectroError(e.ErrorCodes.InvalidLoggerProvided, `Loggers must be of type function`);
+				}
+			}
+
 			config.page = Object.assign({}, config.page, option.page);
 			config.params = Object.assign({}, config.params, option.params);
 			return config;
@@ -933,7 +976,7 @@ class Entity {
 				records.push(Key);
 			}
 		}
-		let batches = utilities.batchItems(records, MaxBatchItems.batchGet);
+		let batches = u.batchItems(records, MaxBatchItems.batchGet);
 		return batches.map(batch => {
 			return {
 				RequestItems: {
@@ -966,7 +1009,7 @@ class Entity {
 					throw new Error("Invalid method type");
 			}
 		}
-		let batches = utilities.batchItems(records, MaxBatchItems.batchWrite);
+		let batches = u.batchItems(records, MaxBatchItems.batchWrite);
 		return batches.map(batch => {
 			return {
 				RequestItems: {
@@ -1220,7 +1263,7 @@ class Entity {
 			let props = Object.keys(item);
 			let missing = require.filter((prop) => !props.includes(prop));
 			if (!missing) {
-				throw new e.ElectroError(e.ErrorCodes.MissingAttribute, `Item is missing attributes: ${utilities.commaSeparatedString(missing)}`);
+				throw new e.ElectroError(e.ErrorCodes.MissingAttribute, `Item is missing attributes: ${u.commaSeparatedString(missing)}`);
 			}
 		}
 
@@ -1229,7 +1272,7 @@ class Entity {
 				throw new Error(`Invalid attribute ${prop}`);
 			}
 			if (restrict.length && !restrict.includes(prop)) {
-				throw new Error(`${prop} is not a valid attribute: ${utilities.commaSeparatedString(restrict)}`);
+				throw new Error(`${prop} is not a valid attribute: ${u.commaSeparatedString(restrict)}`);
 			}
 			if (prop === undefined || skip.includes(prop)) {
 				continue;
@@ -1392,7 +1435,7 @@ class Entity {
 	_makeComparisonQueryParams(index = TableIndex, comparison = "", filter = {}, pk = {}, sk = {}) {
 		let operator = Comparisons[comparison];
 		if (!operator) {
-			throw new Error(`Unexpected comparison operator "${comparison}", expected ${utilities.commaSeparatedString(Object.values(Comparisons))}`);
+			throw new Error(`Unexpected comparison operator "${comparison}", expected ${u.commaSeparatedString(Object.values(Comparisons))}`);
 		}
 		let keyExpressions = this._queryKeyExpressionAttributeBuilder(
 			index,
@@ -1429,7 +1472,7 @@ class Entity {
 			let incompleteAccessPatterns = incomplete.map(({index}) => this.model.translations.indexes.fromIndexToAccessPattern[index]);
 			let missingFacets = incomplete.reduce((result, { missing }) => [...result, ...missing], []);
 			throw new e.ElectroError(e.ErrorCodes.IncompleteCompositeAttributes,
-				`Incomplete composite attributes: Without the composite attributes ${utilities.commaSeparatedString(missingFacets)} the following access patterns cannot be updated: ${utilities.commaSeparatedString(incompleteAccessPatterns.filter((val) => val !== undefined))} `,
+				`Incomplete composite attributes: Without the composite attributes ${u.commaSeparatedString(missingFacets)} the following access patterns cannot be updated: ${u.commaSeparatedString(incompleteAccessPatterns.filter((val) => val !== undefined))} `,
 			);
 		}
 		return complete;
@@ -1648,7 +1691,7 @@ class Entity {
 	_expectFacets(obj = {}, properties = [], type = "key composite attributes") {
 		let [incompletePk, missing, matching] = this._expectProperties(obj, properties);
 		if (incompletePk) {
-			throw new e.ElectroError(e.ErrorCodes.IncompleteCompositeAttributes, `Incomplete or invalid ${type} supplied. Missing properties: ${utilities.commaSeparatedString(missing)}`);
+			throw new e.ElectroError(e.ErrorCodes.IncompleteCompositeAttributes, `Incomplete or invalid ${type} supplied. Missing properties: ${u.commaSeparatedString(missing)}`);
 		} else {
 			return matching;
 		}
@@ -1721,10 +1764,10 @@ class Entity {
 
 		// If keys arent custom, set the prefixes
 		if (!keys.pk.isCustom) {
-			keys.pk.prefix = utilities.formatKeyCasing(pk, tableIndex.pk.casing);
+			keys.pk.prefix = u.formatKeyCasing(pk, tableIndex.pk.casing);
 		}
 		if (!keys.sk.isCustom) {
-			keys.sk.prefix = utilities.formatKeyCasing(sk, tableIndex.sk.casing);
+			keys.sk.prefix = u.formatKeyCasing(sk, tableIndex.sk.casing);
 		}
 
 		return keys;
@@ -1735,7 +1778,7 @@ class Entity {
 			? this.model.indexes[accessPattern].sk.casing
 			: undefined;
 
-		return utilities.formatKeyCasing(key, casing);
+		return u.formatKeyCasing(key, casing);
 	}
 
 	_validateIndex(index) {
@@ -1859,7 +1902,7 @@ class Entity {
 			key = `${key}${supplied[name]}`;
 		}
 
-		return utilities.formatKeyCasing(key, casing);
+		return u.formatKeyCasing(key, casing);
 	}
 
 	_findBestIndexKeyMatch(attributes = {}) {
@@ -2139,7 +2182,7 @@ class Entity {
 			let indexName = index.index || TableIndex;
 			if (seenIndexes[indexName] !== undefined) {
 				if (indexName === TableIndex) {
-					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexes, `Duplicate index defined in model found in Access Pattern '${accessPattern}': '${utilities.formatIndexNameForDisplay(indexName)}'. This could be because you forgot to specify the index name of a secondary index defined in your model.`);
+					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexes, `Duplicate index defined in model found in Access Pattern '${accessPattern}': '${u.formatIndexNameForDisplay(indexName)}'. This could be because you forgot to specify the index name of a secondary index defined in your model.`);
 				} else {
 					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexes, `Duplicate index defined in model found in Access Pattern '${accessPattern}': '${indexName}'`);
 				}
@@ -2148,7 +2191,7 @@ class Entity {
 			let hasSk = !!index.sk;
 			let inCollection = !!index.collection;
 			if (!hasSk && inCollection) {
-				throw new e.ElectroError(e.ErrorCodes.CollectionNoSK, `Invalid Access pattern definition for '${accessPattern}': '${utilities.formatIndexNameForDisplay(indexName)}', contains a collection definition without a defined SK. Collections can only be defined on indexes with a defined SK.`);
+				throw new e.ElectroError(e.ErrorCodes.CollectionNoSK, `Invalid Access pattern definition for '${accessPattern}': '${u.formatIndexNameForDisplay(indexName)}', contains a collection definition without a defined SK. Collections can only be defined on indexes with a defined SK.`);
 			}
 			let collection = index.collection || "";
 			let customFacets = {
@@ -2219,7 +2262,7 @@ class Entity {
 			if (Array.isArray(sk.facets)) {
 				let duplicates = pk.facets.filter(facet => sk.facets.includes(facet));
 				if (duplicates.length !== 0) {
-					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexCompositeAttributes, `The Access Pattern '${accessPattern}' contains duplicate references the composite attribute(s): ${utilities.commaSeparatedString(duplicates)}. Composite attributes may only be used once within an index. If this leaves the Sort Key (sk) without any composite attributes simply set this to be an empty array.`);
+					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexCompositeAttributes, `The Access Pattern '${accessPattern}' contains duplicate references the composite attribute(s): ${u.commaSeparatedString(duplicates)}. Composite attributes may only be used once within an index. If this leaves the Sort Key (sk) without any composite attributes simply set this to be an empty array.`);
 				}
 			}
 
@@ -2322,13 +2365,13 @@ class Entity {
 
 			let pkTemplateIsCompatible = this._compositeTemplateAreCompatible(parsedPKAttributes, index.pk.composite);
 			if (!pkTemplateIsCompatible) {
-				throw new e.ElectroError(e.ErrorCodes.IncompatibleKeyCompositeAttributeTemplate, `Incompatible PK 'template' and 'composite' properties for defined on index "${utilities.formatIndexNameForDisplay(indexName)}". PK "template" string is defined as having composite attributes ${utilities.commaSeparatedString(parsedPKAttributes.attributes)} while PK "composite" array is defined with composite attributes ${utilities.commaSeparatedString(index.pk.composite)}`);
+				throw new e.ElectroError(e.ErrorCodes.IncompatibleKeyCompositeAttributeTemplate, `Incompatible PK 'template' and 'composite' properties for defined on index "${u.formatIndexNameForDisplay(indexName)}". PK "template" string is defined as having composite attributes ${u.commaSeparatedString(parsedPKAttributes.attributes)} while PK "composite" array is defined with composite attributes ${u.commaSeparatedString(index.pk.composite)}`);
 			}
 
 			if (index.sk !== undefined && Array.isArray(index.sk.composite) && typeof index.sk.template === "string") {
 				let skTemplateIsCompatible = this._compositeTemplateAreCompatible(parsedSKAttributes, index.sk.composite);
 				if (!skTemplateIsCompatible) {
-					throw new e.ElectroError(e.ErrorCodes.IncompatibleKeyCompositeAttributeTemplate, `Incompatible SK 'template' and 'composite' properties for defined on index "${utilities.formatIndexNameForDisplay(indexName)}". SK "template" string is defined as having composite attributes ${utilities.commaSeparatedString(parsedSKAttributes.attributes)} while SK "composite" array is defined with composite attributes ${utilities.commaSeparatedString(index.sk.composite)}`);
+					throw new e.ElectroError(e.ErrorCodes.IncompatibleKeyCompositeAttributeTemplate, `Incompatible SK 'template' and 'composite' properties for defined on index "${u.formatIndexNameForDisplay(indexName)}". SK "template" string is defined as having composite attributes ${u.commaSeparatedString(parsedSKAttributes.attributes)} while SK "composite" array is defined with composite attributes ${u.commaSeparatedString(index.sk.composite)}`);
 				}
 			}
 		}
@@ -2356,7 +2399,7 @@ class Entity {
 
 		for (let [name, fn] of Object.entries(filters)) {
 			if (invalidFilterNames.includes(name)) {
-				throw new e.ElectroError(e.ErrorCodes.InvalidFilter, `Invalid filter name: ${name}. Filter cannot be named ${utilities.commaSeparatedString(invalidFilterNames)}`);
+				throw new e.ElectroError(e.ErrorCodes.InvalidFilter, `Invalid filter name: ${name}. Filter cannot be named ${u.commaSeparatedString(invalidFilterNames)}`);
 			} else {
 				normalized[name] = fn;
 			}
@@ -2475,7 +2518,7 @@ class Entity {
 	_parseModel(model, config = {}) {
 		/** start beta/v1 condition **/
 		const {client} = config;
-		let modelVersion = utilities.getModelVersion(model);
+		let modelVersion = u.getModelVersion(model);
 		let service, entity, version, table, name;
 		switch(modelVersion) {
 			case ModelVersions.beta:

package/src/errors.js

@@ -127,6 +127,12 @@ const ErrorCodes = {
     name: "InvalidIndexCompositeWithAttributeName",
     sym: ErrorCode,
   },
+  InvalidListenerProvided: {
+    code: 1020,
+    section: "invalid-listener-provided",
+    name: "InvalidListenerProvided",
+    sym: ErrorCode,
+  },
   MissingAttribute: {
     code: 2001,
     section: "missing-attribute",
@@ -204,7 +210,7 @@ const ErrorCodes = {
     section: "pager-not-unique",
     name: "NoOwnerForPager",
     sym: ErrorCode,
-  },
+  }
 };
 
 function makeMessage(message, section) {

package/src/events.js

@@ -0,0 +1,67 @@
+const e = require("./errors");
+const v = require('./validations');
+
+class EventManager {
+  static createSafeListener(listener) {
+    if (listener === undefined) {
+      return undefined;
+    } if (!v.isFunction(listener)) {
+      throw new e.ElectroError(e.ErrorCodes.InvalidListenerProvided, `Provided listener is not of type 'function'`);
+    } else {
+      return (...params) => {
+        try {
+          listener(...params);
+        } catch(err) {
+          console.error(`Error invoking user supplied listener`, err);
+        }
+      }
+    }
+  }
+
+  static normalizeListeners(listeners = []) {
+    if (!Array.isArray(listeners)) {
+      throw new e.ElectroError(e.ErrorCodes.InvalidListenerProvided, `Listeners must be provided as an array of functions`);
+    }
+    return listeners
+      .map(listener => EventManager.createSafeListener(listener))
+      .filter(listener => {
+        switch (typeof listener) {
+          case 'function':
+            return true;
+          case 'undefined':
+            return false;
+          default:
+            throw new e.ElectroError(e.ErrorCodes.InvalidListenerProvided, `Provided listener is not of type 'function`);
+        }
+      });
+  }
+
+  constructor({listeners = []} = {}) {
+    this.listeners = EventManager.normalizeListeners(listeners);
+  }
+
+  add(listeners = []) {
+    if (!Array.isArray(listeners)) {
+      listeners = [listeners];
+    }
+
+    this.listeners = this.listeners.concat(
+      EventManager.normalizeListeners(listeners)
+    );
+  }
+
+  trigger(event, adHocListeners = []) {
+    const allListeners = [
+      ...this.listeners,
+      ...EventManager.normalizeListeners(adHocListeners)
+    ];
+
+    for (const listener of allListeners) {
+      listener(event);
+    }
+  }
+}
+
+module.exports = {
+  EventManager
+};

package/src/service.js

@@ -58,6 +58,9 @@ class Service {
 
 		this.config = config;
 		this.client = config.client;
+		if (v.isFunction(config.logger)) {
+			this.logger = config.logger;
+		}
 		this.entities = {};
 		this.find = {};
 		this.collectionSchema = {};
@@ -79,6 +82,9 @@ class Service {
 
 		this.config = config;
 		this.client = config.client;
+		if (v.isFunction(config.logger)) {
+			this.logger = config.logger;
+		}
 		this.entities = {};
 		this.find = {};
 		this.collectionSchema = {};

package/src/types.js

@@ -179,7 +179,12 @@ const KeyCasing = {
 	upper: "upper",
 	lower: "lower",
 	default: "default",
-}
+};
+
+const EventSubscriptionTypes = [
+	"query",
+	"results"
+];
 
 module.exports = {
 	Pager,
@@ -208,5 +213,6 @@ module.exports = {
 	FormatToReturnValues,
 	AttributeProxySymbol,
 	ElectroInstanceTypes,
+	EventSubscriptionTypes,
 	AttributeMutationMethods
 };

package/src/util.js

@@ -1,5 +1,6 @@
-const v = require("./validations");
 const t = require("./types");
+const e = require("./errors");
+const v = require("./validations");
 
 function parseJSONPath(path = "") {
   if (typeof path !== "string") {