@aws-amplify/datastore 4.0.12 → 4.0.13-push-notification-dryrun.43

package/src/predicates/next.ts

@@ -26,7 +26,9 @@ type GroupOperator = 'and' | 'or' | 'not';
 type UntypedCondition = {
 	fetch: (storage: StorageAdapter) => Promise<Record<string, any>[]>;
 	matches: (item: Record<string, any>) => Promise<boolean>;
-	copy(extract: GroupCondition): [UntypedCondition, GroupCondition | undefined];
+	copy(
+		extract?: GroupCondition
+	): [UntypedCondition, GroupCondition | undefined];
 	toAST(): any;
 };
 
@@ -89,48 +91,6 @@ const negations = {
 	notContains: 'contains',
 };
 
-/**
- * Given a V1 predicate "seed", applies a list of V2 field-level conditions
- * to the predicate, returning a new/final V1 predicate chain link.
- * @param predicate The base/seed V1 predicate to build on
- * @param conditions The V2 conditions to add to the predicate chain.
- * @param negateChildren Whether the conditions should be negated first.
- * @returns A V1 predicate, with conditions incorporated.
- */
-function applyConditionsToV1Predicate<T>(
-	predicate: T,
-	conditions: FieldCondition[],
-	negateChildren: boolean
-): T {
-	let p = predicate;
-	const finalConditions: FieldCondition[] = [];
-
-	for (const c of conditions) {
-		if (negateChildren) {
-			if (c.operator === 'between') {
-				finalConditions.push(
-					new FieldCondition(c.field, 'lt', [c.operands[0]]),
-					new FieldCondition(c.field, 'gt', [c.operands[1]])
-				);
-			} else {
-				finalConditions.push(
-					new FieldCondition(c.field, negations[c.operator], c.operands)
-				);
-			}
-		} else {
-			finalConditions.push(c);
-		}
-	}
-
-	for (const c of finalConditions) {
-		p = p[c.field](
-			c.operator as never,
-			(c.operator === 'between' ? c.operands : c.operands[0]) as never
-		);
-	}
-	return p;
-}
-
 /**
  * A condition that can operate against a single "primitive" field of a model or item.
  * @member field The field of *some record* to test against.
@@ -151,13 +111,29 @@ export class FieldCondition {
 	 * @param extract Not used. Present only to fulfill the `UntypedCondition` interface.
 	 * @returns A new, identitical `FieldCondition`.
 	 */
-	copy(extract: GroupCondition): [FieldCondition, GroupCondition | undefined] {
+	copy(extract?: GroupCondition): [FieldCondition, GroupCondition | undefined] {
 		return [
 			new FieldCondition(this.field, this.operator, [...this.operands]),
 			undefined,
 		];
 	}
 
+	/**
+	 * Produces a tree structure similar to a graphql condition. The returned
+	 * structure is "dumb" and is intended for another query/condition
+	 * generation mechanism to interpret, such as the cloud or storage query
+	 * builders.
+	 *
+	 * E.g.,
+	 *
+	 * ```json
+	 * {
+	 * 	"name": {
+	 * 		"eq": "robert"
+	 * 	}
+	 * }
+	 * ```
+	 */
 	toAST() {
 		return {
 			[this.field]: {
@@ -169,6 +145,44 @@ export class FieldCondition {
 		};
 	}
 
+	/**
+	 * Produces a new condition (`FieldCondition` or `GroupCondition`) that
+	 * matches the opposite of this condition.
+	 *
+	 * Intended to be used when applying De Morgan's Law, which can be done to
+	 * produce more efficient queries against the storage layer if a negation
+	 * appears in the query tree.
+	 *
+	 * For example:
+	 *
+	 * 1. `name.eq('robert')` becomes `name.ne('robert')`
+	 * 2. `price.between(100, 200)` becomes `m => m.or(m => [m.price.lt(100), m.price.gt(200)])`
+	 *
+	 * @param model The model meta to use when construction a new `GroupCondition`
+	 * for cases where the negation requires multiple `FieldCondition`'s.
+	 */
+	negated(model: ModelMeta<any>) {
+		if (this.operator === 'between') {
+			return new GroupCondition(model, undefined, undefined, 'or', [
+				new FieldCondition(this.field, 'lt', [this.operands[0]]),
+				new FieldCondition(this.field, 'gt', [this.operands[1]]),
+			]);
+		} else if (this.operator === 'beginsWith') {
+			// beginsWith negation doesn't have a good, safe optimation right now.
+			// just re-wrap it in negation. The adapter will have to scan-and-filter,
+			// as is likely optimal for negated beginsWith conditions *anyway*.
+			return new GroupCondition(model, undefined, undefined, 'not', [
+				new FieldCondition(this.field, 'beginsWith', [this.operands[0]]),
+			]);
+		} else {
+			return new FieldCondition(
+				this.field,
+				negations[this.operator],
+				this.operands
+			);
+		}
+	}
+
 	/**
 	 * Not implemented. Not needed. GroupCondition instead consumes FieldConditions and
 	 * transforms them into legacy predicates. (*For now.*)
@@ -193,9 +207,9 @@ export class FieldCondition {
 			ge: () => v >= this.operands[0],
 			lt: () => v < this.operands[0],
 			le: () => v <= this.operands[0],
-			contains: () => v.indexOf(this.operands[0]) > -1,
-			notContains: () => v.indexOf(this.operands[0]) === -1,
-			beginsWith: () => v.startsWith(this.operands[0]),
+			contains: () => v?.indexOf(this.operands[0]) > -1,
+			notContains: () => (!v ? true : v.indexOf(this.operands[0]) === -1),
+			beginsWith: () => v?.startsWith(this.operands[0]),
 			between: () => v >= this.operands[0] && v <= this.operands[1],
 		};
 		const operation = operations[this.operator as keyof typeof operations];
@@ -338,7 +352,7 @@ export class GroupCondition {
 	 * @param extract A node of interest. Its copy will *also* be returned if the node exists.
 	 * @returns [The full copy, the copy of `extract` | undefined]
 	 */
-	copy(extract: GroupCondition): [GroupCondition, GroupCondition | undefined] {
+	copy(extract?: GroupCondition): [GroupCondition, GroupCondition | undefined] {
 		const copied = new GroupCondition(
 			this.model,
 			this.field,
@@ -359,6 +373,33 @@ export class GroupCondition {
 		return [copied, extractedCopy];
 	}
 
+	/**
+	 * Creates a new `GroupCondition` that contains only the local field conditions,
+	 * omitting related model conditions. That resulting `GroupCondition` can be
+	 * used to produce predicates that are compatible with the storage adapters and
+	 * Cloud storage.
+	 *
+	 * @param negate Whether the condition tree should be negated according
+	 * to De Morgan's law.
+	 */
+	withFieldConditionsOnly(negate: boolean) {
+		const negateChildren = negate !== (this.operator === 'not');
+		return new GroupCondition(
+			this.model,
+			undefined,
+			undefined,
+			(negate ? negations[this.operator] : this.operator) as
+				| 'or'
+				| 'and'
+				| 'not',
+			this.operands
+				.filter(o => o instanceof FieldCondition)
+				.map(o =>
+					negateChildren ? (o as FieldCondition).negated(this.model) : o
+				)
+		);
+	}
+
 	/**
 	 * Returns a version of the predicate tree with unnecessary logical groups
 	 * condensed and merged together. This is intended to create a dense tree
@@ -543,9 +584,7 @@ export class GroupCondition {
 						}
 					);
 
-					resultGroups.push(
-						await storage.query(this.model.builder, predicate as any)
-					);
+					resultGroups.push(await storage.query(this.model.builder, predicate));
 				} else {
 					throw new Error('Missing field metadata.');
 				}
@@ -558,17 +597,9 @@ export class GroupCondition {
 		// if conditions is empty at this point, child predicates found no matches.
 		// i.e., we can stop looking and return empty.
 		if (conditions.length > 0) {
-			const predicate = FlatModelPredicateCreator.createFromExisting(
-				this.model.schema,
-				p =>
-					p[operator](c =>
-						applyConditionsToV1Predicate(c, conditions, negateChildren)
-					)
-			);
-
-			resultGroups.push(
-				await storage.query(this.model.builder, predicate as any)
-			);
+			const predicate =
+				this.withFieldConditionsOnly(negateChildren).toStoragePredicate();
+			resultGroups.push(await storage.query(this.model.builder, predicate));
 		} else if (conditions.length === 0 && resultGroups.length === 0) {
 			resultGroups.push(await storage.query(this.model.builder));
 		}
@@ -685,13 +716,15 @@ export class GroupCondition {
 		};
 	}
 
-	toStoragePredicate<T>(
-		baseCondition?: StoragePredicate<T>
-	): StoragePredicate<T> {
-		return FlatModelPredicateCreator.createFromAST(
+	/**
+	 * Turn this predicate group into something a storage adapter
+	 * understands how to use.
+	 */
+	toStoragePredicate<T>(): StoragePredicate<T> {
+		return FlatModelPredicateCreator.createFromAST<T>(
 			this.model.schema,
 			this.toAST()
-		) as unknown as StoragePredicate<T>;
+		) as StoragePredicate<T>;
 	}
 
 	/**
@@ -725,12 +758,6 @@ export class GroupCondition {
  * `predicateFor()` returns objecst with recursive getters. To facilitate this,
  * a `query` and `tail` can be provided to "accumulate" nested conditions.
  *
- * TODO: the sortof-immutable algorithm was originally done to support legacy style
- * predicate branching (`p => p.x.eq(value).y.eq(value)`). i'm not sure this is
- * necessary or beneficial at this point, since we decided that each field condition
- * must flly terminate a branch. is the strong mutation barrier between chain links
- * still necessary or helpful?
- *
  * @param ModelType The ModelMeta used to build child properties.
  * @param field Scopes the query branch to a field.
  * @param query A base query to build on. Omit to start a new query.
@@ -753,7 +780,7 @@ export function recursivePredicateFor<T extends PersistentModel>(
 
 	// our eventual return object, which can be built upon.
 	// next steps will be to add or(), and(), not(), and field.op() methods.
-	const link = {} as any;
+	const link = {} as RecursiveModelPredicate<T>;
 
 	// so it can be looked up later with in the internals when processing conditions.
 	registerPredicateInternals(baseCondition, link);
@@ -772,10 +799,8 @@ export function recursivePredicateFor<T extends PersistentModel>(
 
 	// Adds .or() and .and() methods to the link.
 	// TODO: If revisiting this code, consider writing a Proxy instead.
-	['and', 'or'].forEach(op => {
-		(link as any)[op] = (
-			builder: RecursiveModelPredicateAggregateExtender<T>
-		) => {
+	(['and', 'or'] as const).forEach(op => {
+		link[op] = (builder: RecursiveModelPredicateAggregateExtender<T>) => {
 			// or() and and() will return a copy of the original link
 			// to head off mutability concerns.
 			const { query, newTail } = copyLink();
@@ -832,11 +857,11 @@ export function recursivePredicateFor<T extends PersistentModel>(
 	// For each field on the model schema, we want to add a getter
 	// that creates the appropriate new `link` in the query chain.
 	// TODO: If revisiting, consider a proxy.
-	for (const fieldName in ModelType.schema.fields) {
+	for (const fieldName in ModelType.schema.allFields) {
 		Object.defineProperty(link, fieldName, {
 			enumerable: true,
 			get: () => {
-				const def = ModelType.schema.fields[fieldName];
+				const def = ModelType.schema.allFields![fieldName];
 
 				if (!def.association) {
 					// we're looking at a value field. we need to return a
@@ -856,10 +881,16 @@ export function recursivePredicateFor<T extends PersistentModel>(
 								// the same link is being used elsewhere by the customer.
 								const { query, newTail } = copyLink();
 
+								// normalize operands. if any of the values are `undefiend`, use
+								// `null` instead, because that's what will be stored cross-platform.
+								const normalizedOperands = operands.map(o =>
+									o === undefined ? null : o
+								);
+
 								// add the given condition to the link's TAIL node.
 								// remember: the base link might go N nodes deep! e.g.,
 								newTail?.operands.push(
-									new FieldCondition(fieldName, operator, operands)
+									new FieldCondition(fieldName, operator, normalizedOperands)
 								);
 
 								// A `FinalModelPredicate`.
@@ -929,5 +960,7 @@ export function recursivePredicateFor<T extends PersistentModel>(
 export function predicateFor<T extends PersistentModel>(
 	ModelType: ModelMeta<T>
 ): ModelPredicate<T> & PredicateInternalsKey {
+	// the cast here is just a cheap way to reduce the surface area from
+	// the recursive type.
 	return recursivePredicateFor(ModelType, false) as any as ModelPredicate<T>;
 }