electrodb 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -150,4 +150,8 @@ All notable changes to this project will be documented in this file. Breaking ch
 
 ## [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.
+- 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. [[read more](./README.md#listeners)]
+
+## [1.7.1] - 2022-03-19
+### Added
+- Adding support for the v3 DyanmoDBClient. This change also brings in a new ElectroDB dependency [@aws-sdk/lib-dynamodb](https://www.npmjs.com/package/@aws-sdk/client-dynamodb). [[read more](./README.md#aws-dynamodb-client)]

package/README.md

@@ -205,6 +205,14 @@ tasks
         * [Pagination Example](#pagination-example)
   * [Query Examples](#query-examples)
   * [Query Options](#query-options)
+- [AWS DynamoDB Client](#aws-dynamodb-client)
+  * [V2 Client](#v2-client)
+  * [V3 Client](#v3-client)
+- [Events](#events)
+  * [Query Event](#query-event)
+  * [Results Event](#results-event)
+- [Logging](#logging)
+- [Listeners](#listeners)
 - [Errors:](#errors-)
     + [No Client Defined On Model](#no-client-defined-on-model)
     + [Invalid Identifier](#invalid-identifier)
@@ -4309,6 +4317,146 @@ pages           | ∞                    | How many DynamoDB pages should a quer
 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.
 
+# AWS DynamoDB Client
+ElectroDB supports both the [v2](https://www.npmjs.com/package/aws-sdk) and [v3](https://www.npmjs.com/package/@aws-sdk/client-dynamodb) aws clients. The client can be supplied creating a new Entity or Service, or added to a Entity/Service instance via the `setClient()` method.
+
+*On the instantiation of an `Entity`:*
+```typescript
+import { Entity } from 'electrodb';
+import { DocumentClient } from "aws-sdk/clients/dynamodb";
+const table = "my_table_name";
+const client = new DocumentClient({
+    region: "us-east-1"
+});
+
+const task = new Entity({
+    // your model
+}, {
+    client, // <----- client
+    table,
+});
+```
+
+*On the instantiation of an `Service`:*
+```typescript
+import { Entity } from 'electrodb';
+import { DocumentClient } from "aws-sdk/clients/dynamodb";
+const table = "my_table_name";
+const client = new DocumentClient({
+    region: "us-east-1"
+});
+
+const task = new Entity({
+    // your model
+});
+
+const user = new Entity({
+    // your model
+});
+
+const service = new Service({ task, user }, {
+   client, // <----- client
+   table,
+});
+```
+
+*Via the `setClient` method:*
+```typescript
+import { Entity } from 'electrodb';
+import { DocumentClient } from "aws-sdk/clients/dynamodb";
+const table = "my_table_name";
+const client = new DocumentClient({
+    region: "us-east-1"
+});
+
+const task = new Entity({
+    // your model
+});
+
+task.setClient(client);
+```
+
+## V2 Client
+The [v2](https://www.npmjs.com/package/aws-sdk) sdk will work out of the box with the the DynamoDB DocumentClient.
+
+*Example:*
+```typescript
+import { DocumentClient } from "aws-sdk/clients/dynamodb";
+const client = new DocumentClient({
+    region: "us-east-1"
+});
+```
+
+## V3 Client
+The [v3](https://www.npmjs.com/package/@aws-sdk/client-dynamodb) client will work out of the box with the the DynamoDBClient.
+
+```typescript
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+const client = new DynamoDBClient({
+    region: "us-east-1"
+});
+```
+
+# 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 });
+```
+
 # 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!
 
@@ -4413,66 +4561,6 @@ entity.get({ prop1, prop2 }).go();
 }
 ```
 
-# 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).
 
@@ -4481,7 +4569,7 @@ ElectroDB can be supplied with callbacks (called "Listeners") to be invoked afte
 *On the instantiation of an `Entity`:*
 ```typescript
 import { DynamoDB } from 'aws-sdk';
-import {Entity, ElectroEvent} from 'electrodb';
+import { Entity, ElectroEvent } from 'electrodb';
 
 const table = "my_table_name";
 const client = new DynamoDB.DocumentClient();
@@ -4508,7 +4596,7 @@ const task = new Entity({
 *On the instantiation of an `Service`:*
 ```typescript
 import { DynamoDB } from 'aws-sdk';
-import {Entity, ElectroEvent} from 'electrodb';
+import { Entity, ElectroEvent } from 'electrodb';
 
 const table = "my_table_name";
 const client = new DynamoDB.DocumentClient();

package/index.d.ts

@@ -1120,6 +1120,8 @@ type DocumentClient = {
     batchWrite: DocumentClientMethod;
     batchGet: DocumentClientMethod;
     scan: DocumentClientMethod;
+} | {
+    send: (command: any) => Promise<any>;
 }
 
 type ElectroDBMethodTypes = "put" | "get" | "query" | "scan" | "update" | "delete" | "remove" | "patch" | "create" | "batchGet" | "batchWrite";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrodb",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {
@@ -25,6 +25,8 @@
   },
   "homepage": "https://github.com/tywalch/electrodb#readme",
   "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.54.1",
+    "@aws-sdk/lib-dynamodb": "^3.54.1",
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
     "@types/chai": "^4.2.12",
     "@types/mocha": "^8.0.3",
@@ -59,6 +61,7 @@
     "directory": "test"
   },
   "dependencies": {
-    "jsonschema": "1.2.7"
+    "jsonschema": "1.2.7",
+    "@aws-sdk/lib-dynamodb": "^3.54.1"
   }
 }

package/src/client.js

@@ -0,0 +1,135 @@
+const {isFunction} = require('./validations');
+const {ElectroError, ErrorCodes} = require('./errors');
+const lib = require('@aws-sdk/lib-dynamodb');
+
+const DocumentClientVersions = {
+    v2: 'v2',
+    v3: 'v3',
+    electro: 'electro',
+};
+
+const v3Methods = ['send'];
+const v2Methods = ['get', 'put', 'update', 'delete', 'batchWrite', 'batchGet', 'scan', 'query', 'createSet'];
+const supportedClientVersions = {
+    [DocumentClientVersions.v2]: v2Methods,
+    [DocumentClientVersions.v3]: v3Methods,
+}
+
+class DocumentClientV3Wrapper {
+    static init(client) {
+        return new DocumentClientV3Wrapper(client, lib);
+    }
+
+    constructor(client, lib) {
+        this.client = client;
+        this.lib = lib;
+    }
+
+    promiseWrap(fn) {
+        return {
+            promise: async () => {
+                return fn();
+            }
+        }
+    }
+
+    get(params) {
+        return this.promiseWrap(() => {
+            const command = new this.lib.GetCommand(params);
+            return this.client.send(command);
+        });
+    }
+    put(params) {
+        return this.promiseWrap(() => {
+            const command = new this.lib.PutCommand(params);
+            return this.client.send(command);
+        });
+    }
+    update(params) {
+        return this.promiseWrap(() => {
+            const command = new this.lib.UpdateCommand(params);
+            return this.client.send(command);
+        });
+    }
+    delete(params) {
+        return this.promiseWrap(async () => {
+            const command = new this.lib.DeleteCommand(params);
+            return this.client.send(command);
+        });
+    }
+    batchWrite(params) {
+        return this.promiseWrap(async () => {
+            const command = new this.lib.BatchWriteCommand(params);
+            return this.client.send(command);
+        });
+    }
+    batchGet(params) {
+        return this.promiseWrap(async () => {
+            const command = new this.lib.BatchGetCommand(params);
+            return this.client.send(command);
+        });
+    }
+    scan(params) {
+        return this.promiseWrap(async () => {
+            const command = new this.lib.ScanCommand(params);
+            return this.client.send(command);
+        });
+    }
+    query(params) {
+        return this.promiseWrap(async () => {
+            const command = new this.lib.QueryCommand(params);
+            return this.client.send(command);
+        });
+    }
+    createSet(value) {
+        if (Array.isArray(value)) {
+            return new Set(value);
+        } else {
+            return new Set([value]);
+        }
+    }
+}
+
+function identifyClientVersion(client = {}) {
+    if (client instanceof DocumentClientV3Wrapper) return DocumentClientVersions.electro;
+    for (const [version, methods] of Object.entries(supportedClientVersions)) {
+        const hasMethods = methods.every(method => {
+            return method in client && isFunction(client[method]);
+        });
+        if (hasMethods) {
+            return version;
+        }
+    }
+}
+
+function normalizeClient(client) {
+    if (client === undefined) return client;
+    const version = identifyClientVersion(client);
+    switch(version) {
+        case DocumentClientVersions.v3:
+            return DocumentClientV3Wrapper.init(client);
+        case DocumentClientVersions.v2:
+        case DocumentClientVersions.electro:
+            return client;
+        default:
+            throw new ElectroError(ErrorCodes.InvalidClientProvided, 'Invalid DynamoDB Document Client provided. ElectroDB supports the v2 and v3 DynamoDB Document Clients from the aws-sdk');
+    }
+}
+
+function normalizeConfig(config = {}) {
+    return {
+        ...config,
+        client: normalizeClient(config.client)
+    }
+}
+
+module.exports = {
+    v2Methods,
+    v3Methods,
+    normalizeClient,
+    normalizeConfig,
+    identifyClientVersion,
+    DocumentClientVersions,
+    supportedClientVersions,
+    DocumentClientV3Wrapper,
+};

package/src/entity.js

@@ -7,11 +7,13 @@ const { WhereFactory } = require("./where");
 const { clauses, ChainState } = require("./clauses");
 const {EventManager} = require('./events');
 const validations = require("./validations");
+const c = require('./client');
 const u = require("./util");
 const e = require("./errors");
 
 class Entity {
 	constructor(model, config = {}) {
+		config = c.normalizeConfig(config);
 		this.eventManager = new EventManager({
 			listeners: config.listeners
 		});
@@ -588,7 +590,7 @@ class Entity {
 
 	_setClient(client) {
 		if (client) {
-			this.client = client;
+			this.client = c.normalizeClient(client);
 		}
 	}
 

package/src/errors.js

@@ -133,6 +133,12 @@ const ErrorCodes = {
     name: "InvalidListenerProvided",
     sym: ErrorCode,
   },
+  InvalidClientProvided: {
+    code: 1021,
+    section: "invalid-client-provided",
+    name: "InvalidClientProvided",
+    sym: ErrorCode,
+  },
   MissingAttribute: {
     code: 2001,
     section: "missing-attribute",

package/src/schema.js

@@ -768,21 +768,28 @@ class SetAttribute extends Attribute {
 	_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);
+			switch (getValueType(value)) {
+				case ValueTypes.array:
+					return validate([...value]);
+				case ValueTypes.aws_set:
+					return validate([...value.values]);
+				case ValueTypes.set:
+					return validate(Array.from(value));
+				default:
+					return validate(value);
 			}
 		}
 	}
 
 	fromDDBSet(value) {
-		if (getValueType(value) === ValueTypes.aws_set) {
-			return value.values;
+		switch (getValueType(value)) {
+			case ValueTypes.aws_set:
+				return [...value.values];
+			case ValueTypes.set:
+				return Array.from(value);
+			default:
+				return value;
 		}
-		return value;
 	}
 
 	_createDDBSet(value) {
@@ -820,15 +827,14 @@ class SetAttribute extends Attribute {
 
 	_makeGet(get, items) {
 		this._checkGetSet(get, "get");
-
 		const getter = get || ((attr) => attr);
-
 		return (values, siblings) => {
 			if (values !== undefined) {
 				const data = this.fromDDBSet(values);
 				return getter(data, siblings);
 			}
-			let results = getter(data, siblings);
+			const data = this.fromDDBSet(values);
+			const results = getter(data, siblings);
 			if (results !== undefined) {
 				// if not undefined, try to convert, else no need to return
 				return this.fromDDBSet(results);
@@ -840,9 +846,7 @@ class SetAttribute extends Attribute {
 		this._checkGetSet(set, "set");
 		const setter = set || ((attr) => attr);
 		return (values, siblings) => {
-			const results = values && values.wrapperName === 'Set'
-				? setter(values.values, siblings)
-				: setter(values, siblings)
+			const results = setter(this.fromDDBSet(values), siblings);
 			if (results !== undefined) {
 				return this.toDDBSet(results);
 			}
@@ -879,7 +883,7 @@ class SetAttribute extends Attribute {
 		} else {
 			errors.push(
 				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, errorValues] = this.items.isValid(item);

package/src/service.js

@@ -6,6 +6,7 @@ const { FilterOperations } = require("./operations");
 const { WhereFactory } = require("./where");
 const { getInstanceType, getModelVersion, applyBetaModelOverrides } = require("./util");
 const v = require("./validations");
+const c = require('./client');
 const e = require("./errors");
 const u = require("./util");
 
@@ -104,6 +105,7 @@ class Service {
 	}
 
 	constructor(service = "", config = {}) {
+		config = c.normalizeConfig(config);
 		this.version = ServiceVersions.v1;
 		let type = inferConstructorType(service);
 		switch(type) {