electrodb 1.8.3 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrodb",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {
@@ -8,7 +8,7 @@
     "test-ts": "mocha -r ts-node/register ./test/**.spec.ts",
     "test-all": "mocha ./test/**.spec.js",
     "test-all-local": "LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 node ./test/init.js && LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 mocha ./test/**.spec.js && npm run test-types && LOCAL_DYNAMO_ENDPOINT=http://localhost:8000 npm run test-ts",
-    "test-types": "node ./node_modules/tsd/dist/cli.js",
+    "test-types": "tsd",
     "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",
@@ -43,9 +43,9 @@
     "moment": "2.24.0",
     "nyc": "^15.1.0",
     "source-map-support": "^0.5.19",
-    "ts-node": "^9.0.0",
-    "tsd": "^0.14.0",
-    "typescript": "^4.2.4",
+    "ts-node": "^10.8.1",
+    "tsd": "^0.21.0",
+    "typescript": "^4.7.4",
     "uuid": "7.0.1"
   },
   "keywords": [
@@ -61,7 +61,7 @@
     "directory": "test"
   },
   "dependencies": {
-    "jsonschema": "1.2.7",
-    "@aws-sdk/lib-dynamodb": "^3.54.1"
+    "@aws-sdk/lib-dynamodb": "^3.54.1",
+    "jsonschema": "1.2.7"
   }
 }

package/src/entity.d.ts

@@ -0,0 +1,94 @@
+import {
+  ParseOptions
+} from './types/options';
+import {
+  TableIndexCompositeAttributes,
+  AllTableIndexCompositeAttributes, 
+  ResponseItem, 
+  Item, 
+  Schema, 
+  SetItem, 
+  AddItem, 
+  SubtractItem, 
+  AppendItem, 
+  DeleteItem,
+  RemoveItem,
+  PutItem,
+} from './types/schema';
+
+import {
+  Queries,
+  SetRecord,
+  RemoveRecord,
+  DataUpdateMethodRecord,
+  RecordsActionOptions,
+  SingleRecordOperationOptions,
+  BulkRecordOperationOptions,
+  DeleteRecordOperationOptions,
+  PutRecordOperationOptions,
+  ParseSingleInput,
+  ParseMultiInput
+} from './types/model';
+
+import { ElectroEventListener } from './types/events';
+import { DocumentClient } from './types/client';
+
+export type Resolve<T> = T extends Function | string | number | boolean
+    ? T : {[Key in keyof T]: Resolve<T[Key]>}
+
+export type EntityConfiguration = {
+  table?: string;
+  client?: DocumentClient;
+  listeners?: Array<ElectroEventListener>;
+  logger?: ElectroEventListener;
+};
+
+export class Entity<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> {
+  readonly schema: S;
+  private config?: EntityConfiguration; 
+  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, [Array<Resolve<ResponseItem<A,F,C,S>>>, Array<Resolve<AllTableIndexCompositeAttributes<A,F,C,S>>>], [Array<Resolve<ResponseItem<A,F,C,S>> | null>, Array<Resolve<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>[], AllTableIndexCompositeAttributes<A,F,C,S>[]>;
+
+  put(record: PutItem<A,F,C,S>): PutRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>;
+  put(record: PutItem<A,F,C,S>[]): BulkRecordOperationOptions<A,F,C,S, AllTableIndexCompositeAttributes<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>>
+  update(key: AllTableIndexCompositeAttributes<A,F,C,S>): {
+      set: SetRecord<A,F,C,S, SetItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      remove: RemoveRecord<A,F,C,S, RemoveItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      add: SetRecord<A,F,C,S, AddItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      subtract: SetRecord<A,F,C,S, SubtractItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      append: SetRecord<A,F,C,S, AppendItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      delete: SetRecord<A,F,C,S, DeleteItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      data: DataUpdateMethodRecord<A,F,C,S, Item<A,F,C,S,S["attributes"]>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+  };
+
+  patch(key: AllTableIndexCompositeAttributes<A,F,C,S>): {
+      set: SetRecord<A,F,C,S, SetItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      remove: RemoveRecord<A,F,C,S, RemoveItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      add: SetRecord<A,F,C,S, AddItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      subtract: SetRecord<A,F,C,S, SubtractItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      append: SetRecord<A,F,C,S, AppendItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      delete: SetRecord<A,F,C,S, DeleteItem<A,F,C,S>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+      data: DataUpdateMethodRecord<A,F,C,S, Item<A,F,C,S,S["attributes"]>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
+  };
+  
+  create(record: PutItem<A,F,C,S>): PutRecordOperationOptions<A,F,C,S, ResponseItem<A,F,C,S>>
+
+  find(record: Partial<Item<A,F,C,S,S["attributes"]>>): RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S>>;
+
+  match(record: Partial<Item<A,F,C,S,S["attributes"]>>): RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S>>;
+
+  scan: RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], TableIndexCompositeAttributes<A,F,C,S>>;
+  query: Queries<A,F,C,S>;
+  
+  parse(item: ParseSingleInput, options?: ParseOptions): ResponseItem<A,F,C,S> | null;
+  parse(item: ParseMultiInput, options?: ParseOptions): ResponseItem<A,F,C,S>[];
+  setIdentifier(type: "entity" | "version", value: string): void;
+  client: any;
+}

package/src/entity.js

@@ -277,6 +277,7 @@ class Entity {
 				results,
 			}, config.listeners);
 		}
+
 		return this.client[method](params).promise()
 			.then((results) => {
 				notifyQuery();
@@ -317,14 +318,36 @@ class Entity {
 		return results;
 	}
 
+	_createNewBatchGetOrderMaintainer(config = {}) {
+		const pkName = this.model.translations.keys[TableIndex].pk;
+		const skName = this.model.translations.keys[TableIndex].sk;
+		const enabled = !!config.preserveBatchOrder;
+		const table = this.config.table;
+		const keyFormatter = ((record = {}) => {
+			const pk = record[pkName];
+			const sk = record[skName];
+			return `${pk}${sk}`;
+		});
+
+		return new u.BatchGetOrderMaintainer({
+			table,
+			enabled,
+			keyFormatter,
+		});
+	}
+
 	async executeBulkGet(parameters, config) {
 		if (!Array.isArray(parameters)) {
 			parameters = [parameters];
 		}
-		let concurrent = this._normalizeConcurrencyValue(config.concurrent)
-		let concurrentOperations = u.batchItems(parameters, concurrent);
 
-		let resultsAll = [];
+		const orderMaintainer = this._createNewBatchGetOrderMaintainer(config);
+		orderMaintainer.defineOrder(parameters);
+		let concurrent = this._normalizeConcurrencyValue(config.concurrent);
+		let concurrentOperations = u.batchItems(parameters, concurrent);
+		let resultsAll = config.preserveBatchOrder
+			? new Array(orderMaintainer.getSize()).fill(null)
+			: [];
 		let unprocessedAll = [];
 		for (let operation of concurrentOperations) {
 			await Promise.all(operation.map(async params => {
@@ -333,13 +356,13 @@ class Entity {
 					resultsAll.push(await config.parse(config, response));
 					return;
 				}
-				let [results, unprocessed] = this.formatBulkGetResponse(response, config);
-				for (let r of results) {
-					resultsAll.push(r);
-				}
-				for (let u of unprocessed) {
-					unprocessedAll.push(u);
-				}
+				this.applyBulkGetResponseFormatting({
+					orderMaintainer,
+					resultsAll,
+					unprocessedAll,
+					response,
+					config
+				});
 			}));
 		}
 		return [resultsAll, unprocessedAll];
@@ -467,20 +490,26 @@ class Entity {
 		}
 	}
 
-	formatBulkGetResponse(response = {}, config = {}) {
-		let unprocessed = [];
-		let results = [];
+	applyBulkGetResponseFormatting({
+		resultsAll,
+		unprocessedAll,
+		orderMaintainer,
+		response = {},
+		config = {},
+	}) {
 		const table = config.table || this._getTableName();
 		const index = TableIndex;
+
 		if (!response.UnprocessedKeys || !response.Responses) {
 			throw new Error("Unknown response format");
 		}
+
 		if (response.UnprocessedKeys[table] && response.UnprocessedKeys[table].Keys && Array.isArray(response.UnprocessedKeys[table].Keys)) {
 			for (let value of response.UnprocessedKeys[table].Keys) {
 				if (config && config.unprocessed === UnprocessedTypes.raw) {
-					unprocessed.push(value);
+					unprocessedAll.push(value);
 				} else {
-					unprocessed.push(
+					unprocessedAll.push(
 						this._formatKeysToItem(index, value)
 					);
 				}
@@ -488,10 +517,18 @@ class Entity {
 		}
 
 		if (response.Responses[table] && Array.isArray(response.Responses[table])) {
-			results = this.formatResponse({Items: response.Responses[table]}, index, config);
+			const responses = response.Responses[table];
+			for (let i = 0; i < responses.length; i++) {
+				const item = responses[i];
+				const slot = orderMaintainer.getOrder(item);
+				const formatted = this.formatResponse({Item: item}, index, config);
+				if (slot !== -1) {
+					resultsAll[slot] = formatted;
+				} else {
+					resultsAll.push(formatted);
+				}
+			}
 		}
-
-		return [results, unprocessed];
 	}
 
 	formatResponse(response, index, config = {}) {
@@ -782,6 +819,7 @@ class Entity {
 			_isCollectionQuery: false,
 			pages: undefined,
 			listeners: [],
+			preserveBatchOrder: false,
 		};
 
 		config = options.reduce((config, option) => {
@@ -794,6 +832,10 @@ class Entity {
 				config.params.ReturnValues = FormatToReturnValues[format];
 			}
 
+			if (option.preserveBatchOrder === true) {
+				config.preserveBatchOrder = true;
+			}
+
 			if (option.pages !== undefined) {
 				config.pages = option.pages;
 			}
@@ -2257,22 +2299,6 @@ class Entity {
 				facets.fields.push(sk.field);
 			}
 
-			if (seenIndexFields[pk.field] !== undefined) {
-				throw new e.ElectroError(e.ErrorCodes.DuplicateIndexFields, `Partition Key (pk) on Access Pattern '${accessPattern}' references the field '${pk.field}' which is already referenced by the Access Pattern '${seenIndexFields[pk.field]}'. Fields used for indexes need to be unique to avoid conflicts.`);
-			} else {
-				seenIndexFields[pk.field] = accessPattern;
-			}
-
-			if (sk.field) {
-				if (sk.field === pk.field) {
-					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexFields, `The Access Pattern '${accessPattern}' references the field '${sk.field}' as the field name for both the PK and SK. Fields used for indexes need to be unique to avoid conflicts.`);
-				} else if (seenIndexFields[sk.field] !== undefined) {
-					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexFields, `Sort Key (sk) on Access Pattern '${accessPattern}' references the field '${sk.field}' which is already referenced by the Access Pattern '${seenIndexFields[sk.field]}'. Fields used for indexes need to be unique to avoid conflicts.`);
-				}else {
-					seenIndexFields[sk.field] = accessPattern;
-				}
-			}
-
 			if (Array.isArray(sk.facets)) {
 				let duplicates = pk.facets.filter(facet => sk.facets.includes(facet));
 				if (duplicates.length !== 0) {
@@ -2362,6 +2388,37 @@ class Entity {
 				facets.byField[sk.field][indexName] = sk;
 			}
 
+			if (seenIndexFields[pk.field] !== undefined) {
+				const definition = Object.values(facets.byField[pk.field]).find(definition => definition.index !== indexName)
+				const definitionsMatch = validations.stringArrayMatch(pk.facets, definition.facets);
+				if (!definitionsMatch) {
+					throw new e.ElectroError(e.ErrorCodes.InconsistentIndexDefinition, `Partition Key (pk) on Access Pattern '${u.formatIndexNameForDisplay(accessPattern)}' is defined with the composite attribute(s) ${u.commaSeparatedString(pk.facets)}, but the accessPattern '${u.formatIndexNameForDisplay(definition.index)}' defines this field with the composite attributes ${u.commaSeparatedString(definition.facets)}'. Key fields must have the same composite attribute definitions across all indexes they are involved with`);
+				}
+				seenIndexFields[pk.field].push({accessPattern, type: 'pk'});
+			} else {
+				seenIndexFields[pk.field] = [];
+				seenIndexFields[pk.field].push({accessPattern, type: 'pk'});
+			}
+
+			if (sk.field) {
+				if (sk.field === pk.field) {
+					throw new e.ElectroError(e.ErrorCodes.DuplicateIndexFields, `The Access Pattern '${u.formatIndexNameForDisplay(accessPattern)}' references the field '${sk.field}' as the field name for both the PK and SK. Fields used for indexes need to be unique to avoid conflicts.`);
+				} else if (seenIndexFields[sk.field] !== undefined) {
+					const isAlsoDefinedAsPK = seenIndexFields[sk.field].find(field => field.type === "pk");
+					if (isAlsoDefinedAsPK) {
+						throw new e.ElectroError(e.ErrorCodes.InconsistentIndexDefinition, `The Sort Key (sk) on Access Pattern '${u.formatIndexNameForDisplay(accessPattern)}' references the field '${pk.field}' which is already referenced by the Access Pattern(s) '${u.formatIndexNameForDisplay(isAlsoDefinedAsPK.accessPattern)}' as a Partition Key. Fields mapped to Partition Keys cannot be also mapped to Sort Keys.`);
+					}
+					const definition = Object.values(facets.byField[sk.field]).find(definition => definition.index !== indexName)
+					const definitionsMatch = validations.stringArrayMatch(sk.facets, definition.facets);
+					if (!definitionsMatch) {
+						throw new e.ElectroError(e.ErrorCodes.DuplicateIndexFields, `Sort Key (sk) on Access Pattern '${u.formatIndexNameForDisplay(accessPattern)}' is defined with the composite attribute(s) ${u.commaSeparatedString(sk.facets)}, but the accessPattern '${u.formatIndexNameForDisplay(definition.index)}' defines this field with the composite attributes ${u.commaSeparatedString(definition.facets)}'. Key fields must have the same composite attribute definitions across all indexes they are involved with`);
+					}
+					seenIndexFields[sk.field].push({accessPattern, type: 'sk'});
+				} else {
+					seenIndexFields[sk.field] = [];
+					seenIndexFields[sk.field].push({accessPattern, type: 'sk'});
+				}
+			}
 
 			attributes.forEach(({index, type, name}, j) => {
 				let next = attributes[j + 1] !== undefined ? attributes[j + 1].name : "";

package/src/entity.test-d.ts

@@ -0,0 +1,110 @@
+import { Entity } from './entity';
+
+const entityWithSK = new Entity({
+  model: {
+      entity: "abc",
+      service: "myservice",
+      version: "myversion"
+  },
+  attributes: {
+      attr1: {
+          type: "string",
+          default: "abc",
+          get: (val) => val + 123,
+          set: (val) => (val ?? "") + 456,
+          validate: (val) => !!val,
+      },
+      attr2: {
+          type: "string",
+          // default: () => "sfg",
+          // required: false,
+          validate: (val) => val.length > 0
+      },
+      attr3: {
+          type: ["123", "def", "ghi"] as const,
+          default: "def"
+      },
+      attr4: {
+          type: ["abc", "ghi"] as const,
+          required: true
+      },
+      attr5: {
+          type: "string"
+      },
+      attr6: {
+          type: "number",
+          default: () => 100,
+          get: (val) => val + 5,
+          set: (val) => (val ?? 0) + 5,
+          validate: (val) => true,
+      },
+      attr7: {
+          type: "any",
+          default: () => false,
+          get: (val) => ({key: "value"}),
+          set: (val) => (val ?? 0) + 5,
+          validate: (val) => true,
+      },
+      attr8: {
+          type: "boolean",
+          required: true,
+          get: (val) => !!val,
+          set: (val) => !!val,
+          validate: (val) => !!val,
+      },
+      attr9: {
+          type: "number"
+      },
+      attr10: {
+          type: "boolean"
+      },
+      attr11: {
+        type: 'list',
+        items: {
+            type: 'string'
+        }
+      }
+  },
+  indexes: {
+      myIndex: {
+          collection: "mycollection2",
+          pk: {
+              field: "pk",
+              composite: ["attr1"]
+          },
+          sk: {
+              field: "sk",
+              composite: ["attr2"]
+          }
+      },
+      myIndex2: {
+          collection: "mycollection1",
+          index: "gsi1",
+          pk: {
+              field: "gsipk1",
+              composite: ["attr6", "attr9"]
+          },
+          sk: {
+              field: "gsisk1",
+              composite: ["attr4", "attr5"]
+          }
+      },
+      myIndex3: {
+          collection: "mycollection",
+          index: "gsi2",
+          pk: {
+              field: "gsipk2",
+              composite: ["attr5"]
+          },
+          sk: {
+              field: "gsisk2",
+              composite: ["attr4", "attr3", "attr9"]
+          }
+      }
+  }
+});
+
+entityWithSK.update({
+    attr1: 'abc', 
+    attr2: 'def'
+}).append({})

package/src/errors.js

@@ -139,6 +139,12 @@ const ErrorCodes = {
     name: "InvalidClientProvided",
     sym: ErrorCode,
   },
+  InconsistentIndexDefinition: {
+    code: 1022,
+    section: "inconsistent-index-definition",
+    name: "InvalidClientProvided",
+    sym: ErrorCode,
+  },
   MissingAttribute: {
     code: 2001,
     section: "missing-attribute",

package/src/service.d.ts

@@ -0,0 +1,17 @@
+import { Entity } from './entity';
+import { DocumentClient } from './types/client';
+import { ElectroEventListener } from './types/events';
+import { CollectionQueries, CollectionAssociations } from './types/collections';
+
+export type ServiceConfiguration = {
+  table?: string;
+  client?: DocumentClient;
+  listeners?: Array<ElectroEventListener>;
+  logger?: ElectroEventListener;
+};
+
+export class Service<E extends {[name: string]: Entity<any, any, any, any>}> {
+  entities: E;
+  collections: CollectionQueries<E, CollectionAssociations<E>>
+  constructor(entities: E, config?: ServiceConfiguration);
+}

package/src/types/client.ts

@@ -0,0 +1,15 @@
+type DocumentClientMethod = (parameters: any) => {promise: () => Promise<any>};
+
+export type DocumentClient = {
+    get: DocumentClientMethod;
+    put: DocumentClientMethod;
+    delete: DocumentClientMethod;
+    update: DocumentClientMethod;
+    batchWrite: DocumentClientMethod;
+    batchGet: DocumentClientMethod;
+    scan: DocumentClientMethod;
+    transactGet: DocumentClientMethod;
+    transactWrite: DocumentClientMethod;
+} | {
+    send: (command: any) => Promise<any>;
+}