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

package/lib/predicates/index.js

@@ -9,11 +9,39 @@ function isPredicatesAll(predicate) {
     return predicatesAllSet.has(predicate);
 }
 exports.isPredicatesAll = isPredicatesAll;
+/**
+ * The valid logical grouping keys for a predicate group.
+ */
 var groupKeys = new Set(['and', 'or', 'not']);
+/**
+ * Determines whether an object is a GraphQL style predicate "group", which must be an
+ * object containing a single "group key", which then contains the child condition(s).
+ *
+ * E.g.,
+ *
+ * ```
+ * { and: [ ... ] }
+ * { not: { ... } }
+ * ```
+ *
+ * @param o The object to test.
+ */
 var isGroup = function (o) {
     var keys = tslib_1.__spread(Object.keys(o));
     return keys.length === 1 && groupKeys.has(keys[0]);
 };
+/**
+ * Determines whether an object specifies no conditions and should match everything,
+ * as would be the case with `Predicates.ALL`.
+ *
+ * @param o The object to test.
+ */
+var isEmpty = function (o) {
+    return !Array.isArray(o) && Object.keys(o).length === 0;
+};
+/**
+ * The valid comparison operators that can be used as keys in a predicate comparison object.
+ */
 exports.comparisonKeys = new Set([
     'eq',
     'ne',
@@ -26,16 +54,28 @@ exports.comparisonKeys = new Set([
     'beginsWith',
     'between',
 ]);
+/**
+ * Determines whether an object is a GraphQL style predicate comparison node, which must
+ * be an object containing a single "comparison operator" key, which then contains the
+ * operand or operands to compare against.
+ *
+ * @param o The object to test.
+ */
 var isComparison = function (o) {
     var keys = tslib_1.__spread(Object.keys(o));
     return !Array.isArray(o) && keys.length === 1 && exports.comparisonKeys.has(keys[0]);
 };
+/**
+ * A light check to determine whether an object is a valid GraphQL Condition AST.
+ *
+ * @param o The object to test.
+ */
 var isValid = function (o) {
     if (Array.isArray(o)) {
         return o.every(function (v) { return isValid(v); });
     }
     else {
-        return Object.keys(o).length === 1;
+        return Object.keys(o).length <= 1;
     }
 };
 // This symbol is not used at runtime, only its type (unique symbol)
@@ -58,61 +98,26 @@ exports.Predicates = Predicates;
 var ModelPredicateCreator = /** @class */ (function () {
     function ModelPredicateCreator() {
     }
-    ModelPredicateCreator.createPredicateBuilder = function (modelDefinition) {
-        var modelName = modelDefinition.name;
-        var fieldNames = new Set(Object.keys(modelDefinition.fields));
-        var handler;
-        var predicate = new Proxy({}, (handler = {
-            get: function (_, propertyKey, self) {
-                var groupType = propertyKey;
-                switch (groupType) {
-                    case 'and':
-                    case 'or':
-                    case 'not':
-                        var result_1 = function (newPredicate) {
-                            var group = {
-                                type: groupType,
-                                predicates: [],
-                            };
-                            // Create a new recorder
-                            var tmpPredicateRecorder = new Proxy({}, handler);
-                            // Set the recorder group
-                            ModelPredicateCreator.predicateGroupsMap.set(tmpPredicateRecorder, group);
-                            // Apply the predicates to the recorder (this is the step that records the changes)
-                            newPredicate(tmpPredicateRecorder);
-                            // Push the group to the top-level recorder
-                            ModelPredicateCreator.predicateGroupsMap
-                                .get(self)
-                                .predicates.push(group);
-                            return self;
-                        };
-                        return result_1;
-                    default:
-                    // intentionally blank.
-                }
-                var field = propertyKey;
-                if (!fieldNames.has(field)) {
-                    throw new Error("Invalid field for model. field: " + field + ", model: " + modelName);
-                }
-                var result = function (operator, operand) {
-                    ModelPredicateCreator.predicateGroupsMap
-                        .get(self)
-                        .predicates.push({ field: field, operator: operator, operand: operand });
-                    return self;
-                };
-                return result;
-            },
-        }));
-        var group = {
-            type: 'and',
-            predicates: [],
-        };
-        ModelPredicateCreator.predicateGroupsMap.set(predicate, group);
-        return predicate;
-    };
+    /**
+     * Determines whether the given storage predicate (lookup key) is a predicate
+     * key that DataStore recognizes.
+     *
+     * @param predicate The storage predicate (lookup key) to test.
+     */
     ModelPredicateCreator.isValidPredicate = function (predicate) {
         return ModelPredicateCreator.predicateGroupsMap.has(predicate);
     };
+    /**
+     * Looks for the storage predicate AST that corresponds to a given storage
+     * predicate key.
+     *
+     * The key must have been created internally by a DataStore utility
+     * method, such as `ModelPredicate.createFromAST()`.
+     *
+     * @param predicate The predicate reference to look up.
+     * @param throwOnInvalid Whether to throw an exception if the predicate
+     * isn't a valid DataStore predicate.
+     */
     ModelPredicateCreator.getPredicates = function (predicate, throwOnInvalid) {
         if (throwOnInvalid === void 0) { throwOnInvalid = true; }
         if (throwOnInvalid && !ModelPredicateCreator.isValidPredicate(predicate)) {
@@ -120,25 +125,25 @@ var ModelPredicateCreator = /** @class */ (function () {
         }
         return ModelPredicateCreator.predicateGroupsMap.get(predicate);
     };
-    // transforms cb-style predicate into Proxy
-    ModelPredicateCreator.createFromExisting = function (modelDefinition, existing) {
-        if (!existing || !modelDefinition) {
-            return undefined;
-        }
-        return existing(ModelPredicateCreator.createPredicateBuilder(modelDefinition));
-    };
-    ModelPredicateCreator.createForSingleField = function (modelDefinition, fieldName, value) {
-        return ModelPredicateCreator.createPredicateBuilder(modelDefinition)[fieldName]('eq', value);
-    };
+    /**
+     * using the PK values from the given `model` (which can be a partial of T
+     * Creates a predicate that matches an instance described by `modelDefinition`
+     * that contains only PK field values.)
+     *
+     * @param modelDefinition The model definition to create a predicate for.
+     * @param model The model instance to extract value equalities from.
+     */
     ModelPredicateCreator.createForPk = function (modelDefinition, model) {
         var keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
         var keyValues = util_1.extractPrimaryKeyValues(model, keyFields);
-        var modelPredicate = ModelPredicateCreator.createPredicateBuilder(modelDefinition);
-        keyFields.forEach(function (field, idx) {
-            var operand = keyValues[idx];
-            modelPredicate = modelPredicate[field]('eq', operand);
+        var predicate = this.createFromAST(modelDefinition, {
+            and: keyFields.map(function (field, idx) {
+                var _a;
+                var operand = keyValues[idx];
+                return _a = {}, _a[field] = { eq: operand }, _a;
+            }),
         });
-        return modelPredicate;
+        return predicate;
     };
     /**
      * Searches a `Model` table for records matching the given equalities object.
@@ -150,60 +155,50 @@ var ModelPredicateCreator = /** @class */ (function () {
      * @param flatEqualities An object holding field equalities to search for.
      */
     ModelPredicateCreator.createFromFlatEqualities = function (modelDefinition, flatEqualities) {
-        var e_1, _a;
-        var predicate = ModelPredicateCreator.createPredicateBuilder(modelDefinition);
-        try {
-            for (var _b = tslib_1.__values(Object.entries(flatEqualities)), _c = _b.next(); !_c.done; _c = _b.next()) {
-                var _d = tslib_1.__read(_c.value, 2), field = _d[0], value = _d[1];
-                predicate = predicate[field]('eq', value);
-            }
-        }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
-        finally {
-            try {
-                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
-            }
-            finally { if (e_1) throw e_1.error; }
-        }
-        return predicate;
-    };
-    ModelPredicateCreator.createGroupFromExisting = function (modelDefinition, group, existingPredicates) {
-        var outer = ModelPredicateCreator.createPredicateBuilder(modelDefinition);
-        outer = outer[group](function (seed) {
-            var e_2, _a;
-            var _b;
-            var inner = seed;
-            try {
-                for (var existingPredicates_1 = tslib_1.__values(existingPredicates), existingPredicates_1_1 = existingPredicates_1.next(); !existingPredicates_1_1.done; existingPredicates_1_1 = existingPredicates_1.next()) {
-                    var existing = existingPredicates_1_1.value;
-                    if (typeof existing === 'function') {
-                        inner = existing(inner);
-                    }
-                    else {
-                        (_b = ModelPredicateCreator.predicateGroupsMap
-                            .get(inner)) === null || _b === void 0 ? void 0 : _b.predicates.push(ModelPredicateCreator.predicateGroupsMap.get(existing));
-                    }
-                }
-            }
-            catch (e_2_1) { e_2 = { error: e_2_1 }; }
-            finally {
-                try {
-                    if (existingPredicates_1_1 && !existingPredicates_1_1.done && (_a = existingPredicates_1.return)) _a.call(existingPredicates_1);
-                }
-                finally { if (e_2) throw e_2.error; }
-            }
-            return inner;
-        });
-        return outer;
+        var ast = {
+            and: Object.entries(flatEqualities).map(function (_a) {
+                var _b;
+                var _c = tslib_1.__read(_a, 2), k = _c[0], v = _c[1];
+                return (_b = {}, _b[k] = { eq: v }, _b);
+            }),
+        };
+        return this.createFromAST(modelDefinition, ast);
     };
-    ModelPredicateCreator.transformGraphQLtoPredicateAST = function (gql) {
+    /**
+     * Accepts a GraphQL style filter predicate tree and transforms it into an
+     * AST that can be used for a storage adapter predicate. Example input:
+     *
+     * ```js
+     * {
+     * 	and: [
+     * 		{ name: { eq: "Bob Jones" } },
+     * 		{ age: { between: [32, 64] } },
+     * 		{ not: {
+     * 			or: [
+     * 				{ favoriteFood: { eq: 'pizza' } },
+     * 				{ favoriteFood: { eq: 'tacos' } },
+     * 			]
+     * 		}}
+     * 	]
+     * }
+     * ```
+     *
+     * @param gql GraphQL style filter node.
+     */
+    ModelPredicateCreator.transformGraphQLFilterNodeToPredicateAST = function (gql) {
         var _this = this;
         if (!isValid(gql)) {
-            throw new Error('Invalid QGL AST: ' + gql);
+            throw new Error('Invalid GraphQL Condition or subtree: ' + gql);
         }
-        if (isGroup(gql)) {
+        if (isEmpty(gql)) {
+            return {
+                type: 'and',
+                predicates: [],
+            };
+        }
+        else if (isGroup(gql)) {
             var groupkey = Object.keys(gql)[0];
-            var children = this.transformGraphQLtoPredicateAST(gql[groupkey]);
+            var children = this.transformGraphQLFilterNodeToPredicateAST(gql[groupkey]);
             return {
                 type: groupkey,
                 predicates: Array.isArray(children) ? children : [children],
@@ -218,19 +213,44 @@ var ModelPredicateCreator = /** @class */ (function () {
         }
         else {
             if (Array.isArray(gql)) {
-                return gql.map(function (o) { return _this.transformGraphQLtoPredicateAST(o); });
+                return gql.map(function (o) { return _this.transformGraphQLFilterNodeToPredicateAST(o); });
             }
             else {
                 var fieldKey = Object.keys(gql)[0];
-                return tslib_1.__assign({ field: fieldKey }, this.transformGraphQLtoPredicateAST(gql[fieldKey]));
+                return tslib_1.__assign({ field: fieldKey }, this.transformGraphQLFilterNodeToPredicateAST(gql[fieldKey]));
             }
         }
     };
+    /**
+     * Accepts a GraphQL style filter predicate tree and transforms it into a predicate
+     * that storage adapters understand. Example input:
+     *
+     * ```js
+     * {
+     * 	and: [
+     * 		{ name: { eq: "Bob Jones" } },
+     * 		{ age: { between: [32, 64] } },
+     * 		{ not: {
+     * 			or: [
+     * 				{ favoriteFood: { eq: 'pizza' } },
+     * 				{ favoriteFood: { eq: 'tacos' } },
+     * 			]
+     * 		}}
+     * 	]
+     * }
+     * ```
+     *
+     * @param modelDefinition The model that the AST/predicate must be compatible with.
+     * @param ast The graphQL style AST that should specify conditions for `modelDefinition`.
+     */
     ModelPredicateCreator.createFromAST = function (modelDefinition, ast) {
-        var predicate = ModelPredicateCreator.createPredicateBuilder(modelDefinition);
-        ModelPredicateCreator.predicateGroupsMap.set(predicate, this.transformGraphQLtoPredicateAST(ast));
-        return predicate;
+        var key = {};
+        ModelPredicateCreator.predicateGroupsMap.set(key, this.transformGraphQLFilterNodeToPredicateAST(ast));
+        return key;
     };
+    /**
+     * Map of storage predicates (key objects) to storage predicate AST's.
+     */
     ModelPredicateCreator.predicateGroupsMap = new WeakMap();
     return ModelPredicateCreator;
 }());

package/lib/predicates/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/predicates/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/predicates/index.ts"],"names":[],"mappings":"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"}

package/lib/predicates/next.d.ts

@@ -4,7 +4,7 @@ declare type GroupOperator = 'and' | 'or' | 'not';
 declare 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;
 };
 /**
@@ -35,12 +35,45 @@ export declare 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];
+    /**
+     * 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(): {
         [x: string]: {
             [x: string]: string | string[];
         };
     };
+    /**
+     * 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>): GroupCondition | FieldCondition;
     /**
      * Not implemented. Not needed. GroupCondition instead consumes FieldConditions and
      * transforms them into legacy predicates. (*For now.*)
@@ -166,7 +199,17 @@ export declare 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];
+    /**
+     * 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): GroupCondition;
     /**
      * Returns a version of the predicate tree with unnecessary logical groups
      * condensed and merged together. This is intended to create a dense tree
@@ -230,7 +273,11 @@ export declare class GroupCondition {
     toAST(): {
         [x: string]: any[];
     };
-    toStoragePredicate<T>(baseCondition?: StoragePredicate<T>): StoragePredicate<T>;
+    /**
+     * Turn this predicate group into something a storage adapter
+     * understands how to use.
+     */
+    toStoragePredicate<T>(): StoragePredicate<T>;
     /**
      * A JSON representation that's good for debugging.
      */
@@ -258,12 +305,6 @@ export declare 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.