electrodb 1.4.7 → 1.6.1

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;
 			}
 
@@ -1806,54 +1885,105 @@ class Entity {
 		return utilities.formatKeyCasing(key, casing);
 	}
 
-	_findBestIndexKeyMatch(attributes) {
-		let candidates = this.model.facets.bySlot.map((val, i) => i);
+	_findBestIndexKeyMatch(attributes = {}) {
+		// an array of arrays, representing the order of pk and sk composites specified for each index, and then an
+		// array with each access pattern occupying the same array index.
 		let facets = this.model.facets.bySlot;
-		let match;
-		let keys = {};
-		for (let i = 0; i < facets.length; i++) {
-			let currentMatches = [];
-			let nextMatches = [];
-			for (let j = 0; j < candidates.length; j++) {
-				let slot = candidates[j];
-				if (!facets[i][slot]) {
-					continue;
-				}
-				let name = facets[i][slot].name;
-				let next = facets[i][slot].next;
-				let index = facets[i][slot].index;
-				let type = facets[i][slot].type;
-				let match = !!attributes[name];
-				let matchNext = !!attributes[next];
-				if (match) {
-					keys[index] = keys[index] || [];
-					keys[index].push({ name, type });
-					currentMatches.push(slot);
-					if (matchNext) {
-						nextMatches.push(slot);
-					}
+		// a flat array containing the match results of each access pattern, in the same array index they occur within
+		// bySlot above
+		let matches = [];
+		for (let f = 0; f < facets.length; f++) {
+			const slots = facets[f] || [];
+			for (let s = 0; s < slots.length; s++) {
+				const accessPatternSlot = slots[s];
+				matches[s] = matches[s] || {
+					index: accessPatternSlot.index,
+					allKeys: false,
+					hasSk: false,
+					count: 0,
+					done: false,
+					keys: []
 				}
-			}
-			if (currentMatches.length) {
-				if (nextMatches.length) {
-					candidates = [...nextMatches];
+				// already determined to be out of contention on prior iteration
+				const indexOutOfContention = matches[s].done;
+				// composite shorter than other indexes
+				const lacksAttributeAtSlot = !accessPatternSlot;
+				// attribute at this slot is not in the object provided
+				const attributeNotProvided = accessPatternSlot && attributes[accessPatternSlot.name] === undefined;
+				// if the next attribute is a sort key then all partition keys were provided
+				const nextAttributeIsSortKey = accessPatternSlot && accessPatternSlot.next && facets[f+1][s].type === "sk";
+				// if no keys are left then all attribute requirements were met (remember indexes don't require a sort key)
+				const hasAllKeys = accessPatternSlot && !accessPatternSlot.next;
+
+				// no sense iterating on items we know to be "done"
+				if (indexOutOfContention || lacksAttributeAtSlot || attributeNotProvided) {
+					matches[s].done = true;
 					continue;
-				} else {
-					match = facets[i][currentMatches[0]].index;
-					break;
 				}
-			} else if (i === 0) {
-				break;
-			} else {
-				match = (candidates[0] !== undefined && facets[i][candidates[0]].index) || TableIndex;
-				break;
+
+				// if the next attribute is a sort key (and you reached this line) then you have fulfilled all the
+				// partition key requirements for this index
+				if (nextAttributeIsSortKey) {
+					matches[s].hasSk = true;
+				// if you reached this step and there are no more attributes, then you fulfilled the index
+				} else if (hasAllKeys) {
+					matches[s].allKeys = true;
+				}
+
+				// number of successfully fulfilled attributes plays into the ranking heuristic
+				matches[s].count++;
+
+				// note the names/types of fulfilled attributes
+				matches[s].keys.push({
+					name: accessPatternSlot.name,
+					type: accessPatternSlot.type
+				});
 			}
 		}
-		return {
-			keys: keys[match] || [],
-			index: match || TableIndex,
-			shouldScan: match === undefined
-		};
+		// the highest count of matched attributes among all access patterns
+		let max = 0;
+		matches = matches
+			// remove incomplete indexes
+			.filter(match => match.hasSk || match.allKeys)
+			// calculate max attribute match
+			.map(match => {
+				max = Math.max(max, match.count);
+				return match;
+			});
+
+		// matched contains the ranked attributes. The closer an element is to zero the "higher" the rank.
+		const matched = [];
+		for (let m = 0; m < matches.length; m++) {
+			const match = matches[m];
+			// a finished primary index is most ideal (could be a get)
+			const primaryIndexIsFinished = match.index === "" && match.allKeys;
+			// if there is a tie for matched index attributes, primary index should win
+			const primaryIndexIsMostMatched = match.index === "" && match.count === max;
+			// composite attributes are complete
+			const indexRequirementsFulfilled = match.allKeys;
+			// having the most matches is important
+			const hasTheMostAttributeMatches = match.count === max;
+			if (primaryIndexIsFinished) {
+				matched[0] = match;
+			} else if (primaryIndexIsMostMatched) {
+				matched[1] = match;
+			} else if (indexRequirementsFulfilled) {
+				matched[2] = match;
+			} else if (hasTheMostAttributeMatches) {
+				matched[3] = match;
+			}
+		}
+		// find the first non-undefined element (best ranked) -- if possible
+		const match = matched.find(value => !!value);
+		let keys = [];
+		let index = "";
+		let shouldScan = true;
+		if (match) {
+			keys = match.keys;
+			index = match.index;
+			shouldScan = false;
+		}
+		return { keys, index, shouldScan };
 	}
 
 	/* istanbul ignore next */
@@ -1890,7 +2020,7 @@ class Entity {
 				type = "name";
 			} else if (char === "}" && type === "name") {
 				if (current.name.match(/^\s*$/)) {
-					throw new e.ElectroError(e.ErrorCodes.InvalidKeyCompositeAttributeTemplate, `Invalid key composite attribute template. Empty expression "\${${current.name}" provided. Expected attribute name.`);
+					throw new e.ElectroError(e.ErrorCodes.InvalidKeyCompositeAttributeTemplate, `Invalid key composite attribute template. Empty expression "\${${current.name}}" provided. Expected attribute name.`);
 				}
 				attributes.push({name: current.name, label: current.label});
 				current.name = "";

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
 };