@aws-amplify/datastore 4.0.17 → 4.0.18-unstable-v5.5

package/lib/datastore/datastore.d.ts

@@ -54,12 +54,39 @@ declare const initSchema: (userSchema: Schema) => Record<string, PersistentModel
  */
 export declare type ModelInstanceCreator = typeof modelInstanceCreator;
 declare function modelInstanceCreator<T extends PersistentModel>(modelConstructor: PersistentModelConstructor<T>, init: Partial<T>): T;
+/**
+ * An eventually loaded related model instance.
+ */
 export declare class AsyncItem<T> extends Promise<T> {
 }
+/**
+ * A collection of related model instances.
+ *
+ * This collection can be async-iterated or turned directly into an array using `toArray()`.
+ */
 export declare class AsyncCollection<T> implements AsyncIterable<T> {
     private values;
     constructor(values: Array<any> | Promise<Array<any>>);
+    /**
+     * Facilitates async iteration.
+     *
+     * ```ts
+     * for await (const item of collection) {
+     *   handle(item)
+     * }
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+     */
     [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Turns the collection into an array, up to the amount specified in `max` param.
+     *
+     * ```ts
+     * const all = await collection.toArray();
+     * const first100 = await collection.toArray({max: 100});
+     * ```
+     */
     toArray({ max, }?: {
         max?: number;
     }): Promise<T[]>;
@@ -137,8 +164,8 @@ declare class DataStore {
     /**
      * If not already done:
      * 1. Attaches and initializes storage.
-     * 1. Loads the schema and records metadata.
-     * 1. If `this.amplifyConfig.aws_appsync_graphqlEndpoint` contains a URL,
+     * 2. Loads the schema and records metadata.
+     * 3. If `this.amplifyConfig.aws_appsync_graphqlEndpoint` contains a URL,
      * attaches a sync engine, starts it, and subscribes.
      */
     start: () => Promise<void>;

package/lib/datastore/datastore.js

@@ -25,9 +25,12 @@ var isNode = core_1.browserOrNode().isNode;
 var SETTING_SCHEMA_VERSION = 'schemaVersion';
 var schema;
 var modelNamespaceMap = new WeakMap();
-// stores data for crafting the correct update mutation input for a model
-// Patch[] - array of changed fields and metadata
-// PersistentModel - the source model, used for diffing object-type fields
+/**
+ * Stores data for crafting the correct update mutation input for a model.
+ *
+ * - `Patch[]` - array of changed fields and metadata.
+ * - `PersistentModel` - the source model, used for diffing object-type fields.
+ */
 var modelPatchesMap = new WeakMap();
 var getModelDefinition = function (modelConstructor) {
     var namespace = modelNamespaceMap.get(modelConstructor);
@@ -36,11 +39,6 @@ var getModelDefinition = function (modelConstructor) {
         : undefined;
     return definition;
 };
-var getModelPKFieldName = function (modelConstructor) {
-    var _a, _b, _c;
-    var namespace = modelNamespaceMap.get(modelConstructor);
-    return ((namespace && ((_c = (_b = (_a = schema.namespaces) === null || _a === void 0 ? void 0 : _a[namespace]) === null || _b === void 0 ? void 0 : _b.keys) === null || _c === void 0 ? void 0 : _c[modelConstructor.name].primaryKey)) || ['id']);
-};
 /**
  * Determine what the managed timestamp field names are for the given model definition
  * and return the mapping.
@@ -64,13 +62,14 @@ var getTimestampFields = function (definition) {
     var customFields = timestampFieldsMap || {};
     return tslib_1.__assign(tslib_1.__assign({}, defaultFields), customFields);
 };
+/**
+ * Determines whether the given object is a Model Constructor that DataStore can
+ * safely use to construct objects and discover related metadata.
+ *
+ * @param obj The object to test.
+ */
 var isValidModelConstructor = function (obj) {
-    if (util_1.isModelConstructor(obj) && modelNamespaceMap.has(obj)) {
-        return true;
-    }
-    else {
-        return false;
-    }
+    return util_1.isModelConstructor(obj) && modelNamespaceMap.has(obj);
 };
 var namespaceResolver = function (modelConstructor) {
     var resolver = modelNamespaceMap.get(modelConstructor);
@@ -79,13 +78,32 @@ var namespaceResolver = function (modelConstructor) {
     }
     return resolver;
 };
+/**
+ * Creates a predicate without any conditions that can be passed to customer
+ * code to have conditions added to it.
+ *
+ * For example, in this query:
+ *
+ * ```ts
+ * await DataStore.query(
+ * 	Model,
+ * 	item => item.field.eq('value')
+ * );
+ * ```
+ *
+ * `buildSeedPredicate(Model)` is used to create `item`, which is passed to the
+ * predicate function, which in turn uses that "seed" predicate (`item`) to build
+ * a predicate tree.
+ *
+ * @param modelConstructor The model the predicate will query.
+ */
 var buildSeedPredicate = function (modelConstructor) {
     if (!modelConstructor)
         throw new Error('Missing modelConstructor');
     var modelSchema = getModelDefinition(modelConstructor);
     if (!modelSchema)
         throw new Error('Missing modelSchema');
-    var pks = getModelPKFieldName(modelConstructor);
+    var pks = util_1.extractPrimaryKeyFieldNames(modelSchema);
     if (!pks)
         throw new Error('Could not determine PK');
     return next_1.recursivePredicateFor({
@@ -209,15 +227,21 @@ var initSchema = function (userSchema) {
                 return connectedModels.push(field.type.model);
             });
             modelAssociations.set(model.name, connectedModels);
+            // Precompute model info (such as pk fields) so that downstream schema consumers
+            // (such as predicate builders) don't have to reach back into "DataStore" space
+            // to go looking for it.
             Object.values(model.fields).forEach(function (field) {
-                if (typeof field.type === 'object' &&
-                    !Object.getOwnPropertyDescriptor(field.type, 'modelConstructor')) {
+                var relatedModel = userClasses[field.type.model];
+                if (util_1.isModelConstructor(relatedModel)) {
                     Object.defineProperty(field.type, 'modelConstructor', {
                         get: function () {
+                            var relatedModelDefinition = getModelDefinition(relatedModel);
+                            if (!relatedModelDefinition)
+                                throw new Error("Could not find model definition for " + relatedModel.name);
                             return {
-                                builder: userClasses[field.type.model],
-                                schema: schema.namespaces[namespace].models[field.type.model],
-                                pkField: getModelPKFieldName(userClasses[field.type.model]),
+                                builder: relatedModel,
+                                schema: relatedModelDefinition,
+                                pkField: util_1.extractPrimaryKeyFieldNames(relatedModelDefinition),
                             };
                         },
                     });
@@ -570,6 +594,7 @@ var normalize = function (modelDefinition, draft) {
     }
 };
 var createModelClass = function (modelDefinition) {
+    var e_5, _a;
     var clazz = /** @class */ (function () {
         function Model(init) {
             var instance = immer_1.produce(this, function (draft) {
@@ -666,16 +691,16 @@ var createModelClass = function (modelDefinition) {
     }());
     clazz[immer_1.immerable] = true;
     Object.defineProperty(clazz, 'name', { value: modelDefinition.name });
-    var _loop_1 = function (field) {
-        if (!types_1.isFieldAssociation(modelDefinition, field)) {
-            return "continue";
-        }
-        var _a = modelDefinition.fields[field], type = _a.type, localAssociation = _a.association, _b = _a.association, targetName = _b.targetName, targetNames = _b.targetNames;
-        var relationship = new relationship_1.ModelRelationship({
-            builder: clazz,
-            schema: modelDefinition,
-            pkField: util_1.extractPrimaryKeyFieldNames(modelDefinition),
-        }, field);
+    // Add getters/setters for relationship fields.
+    //  getter - for lazy loading
+    //  setter - for FK management
+    var allModelRelationships = relationship_1.ModelRelationship.allFrom({
+        builder: clazz,
+        schema: modelDefinition,
+        pkField: util_1.extractPrimaryKeyFieldNames(modelDefinition),
+    });
+    var _loop_1 = function (relationship) {
+        var field = relationship.field;
         Object.defineProperty(clazz.prototype, modelDefinition.fields[field].name, {
             set: function (model) {
                 if (!(typeof model === 'object' || typeof model === 'undefined'))
@@ -701,6 +726,7 @@ var createModelClass = function (modelDefinition) {
                         }
                     }
                 }
+                // if the relationship can be managed automagically, set the FK's
                 if (relationship.isComplete) {
                     for (var i = 0; i < relationship.localJoinFields.length; i++) {
                         this[relationship.localJoinFields[i]] = model === null || model === void 0 ? void 0 : model[relationship.remoteJoinFields[i]];
@@ -713,22 +739,41 @@ var createModelClass = function (modelDefinition) {
             },
             get: function () {
                 var _this = this;
+                /**
+                 * Bucket for holding related models instances specific to `this` instance.
+                 */
                 var instanceMemos = modelInstanceAssociationsMap.has(this)
                     ? modelInstanceAssociationsMap.get(this)
                     : modelInstanceAssociationsMap.set(this, {}).get(this);
+                // if the memos already has a result for this field, we'll use it.
+                // there is no "cache" invalidation of any kind; memos are permanent to
+                // keep an immutable perception of the instance.
                 if (!instanceMemos.hasOwnProperty(field)) {
+                    // before we populate the memo, we need to know where to look for relatives.
+                    // today, this only supports DataStore. Models aren't managed elsewhere in Amplify.
                     if (exports.getAttachment(this) === ModelAttachment.DataStore) {
+                        // when we fetch the results using a query constructed under the guidance
+                        // of the relationship metadata, we DO NOT AWAIT resolution. we want to
+                        // drop the promise into the memo's synchronously, eliminating the chance
+                        // for a race.
                         var resultPromise = instance.query(relationship.remoteModelConstructor, function (base) {
                             return base.and(function (q) {
                                 return relationship.remoteJoinFields.map(function (field, index) {
+                                    // TODO: anything we can use instead of `any` here?
                                     return q[field].eq(_this[relationship.localJoinFields[index]]);
                                 });
                             });
                         });
+                        // results in hand, how we return them to the caller depends on the relationship type.
                         if (relationship.type === 'HAS_MANY') {
+                            // collections should support async iteration, even though we don't
+                            // leverage it fully [yet].
                             instanceMemos[field] = new AsyncCollection(resultPromise);
                         }
                         else {
+                            // non-collections should only ever return 1 value *or nothing*.
+                            // if we have more than 1 record, something's amiss. it's not our job
+                            // pick a result for the customer. it's our job to say "something's wrong."
                             instanceMemos[field] = resultPromise.then(function (rows) {
                                 if (rows.length > 1) {
                                     // should never happen for a HAS_ONE or BELONGS_TO.
@@ -758,11 +803,24 @@ var createModelClass = function (modelDefinition) {
             },
         });
     };
-    for (var field in modelDefinition.fields) {
-        _loop_1(field);
+    try {
+        for (var allModelRelationships_1 = tslib_1.__values(allModelRelationships), allModelRelationships_1_1 = allModelRelationships_1.next(); !allModelRelationships_1_1.done; allModelRelationships_1_1 = allModelRelationships_1.next()) {
+            var relationship = allModelRelationships_1_1.value;
+            _loop_1(relationship);
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (allModelRelationships_1_1 && !allModelRelationships_1_1.done && (_a = allModelRelationships_1.return)) _a.call(allModelRelationships_1);
+        }
+        finally { if (e_5) throw e_5.error; }
     }
     return clazz;
 };
+/**
+ * An eventually loaded related model instance.
+ */
 var AsyncItem = /** @class */ (function (_super) {
     tslib_1.__extends(AsyncItem, _super);
     function AsyncItem() {
@@ -771,10 +829,26 @@ var AsyncItem = /** @class */ (function (_super) {
     return AsyncItem;
 }(Promise));
 exports.AsyncItem = AsyncItem;
+/**
+ * A collection of related model instances.
+ *
+ * This collection can be async-iterated or turned directly into an array using `toArray()`.
+ */
 var AsyncCollection = /** @class */ (function () {
     function AsyncCollection(values) {
         this.values = values;
     }
+    /**
+     * Facilitates async iteration.
+     *
+     * ```ts
+     * for await (const item of collection) {
+     *   handle(item)
+     * }
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+     */
     AsyncCollection.prototype[Symbol.asyncIterator] = function () {
         var _this = this;
         var values;
@@ -808,11 +882,19 @@ var AsyncCollection = /** @class */ (function () {
             }); },
         };
     };
+    /**
+     * Turns the collection into an array, up to the amount specified in `max` param.
+     *
+     * ```ts
+     * const all = await collection.toArray();
+     * const first100 = await collection.toArray({max: 100});
+     * ```
+     */
     AsyncCollection.prototype.toArray = function (_a) {
         var _b = (_a === void 0 ? {} : _a).max, max = _b === void 0 ? Number.MAX_SAFE_INTEGER : _b;
-        var e_5, _c;
+        var e_6, _c;
         return tslib_1.__awaiter(this, void 0, void 0, function () {
-            var output, i, _d, _e, element, e_5_1;
+            var output, i, _d, _e, element, e_6_1;
             return tslib_1.__generator(this, function (_f) {
                 switch (_f.label) {
                     case 0:
@@ -838,8 +920,8 @@ var AsyncCollection = /** @class */ (function () {
                     case 4: return [3 /*break*/, 2];
                     case 5: return [3 /*break*/, 12];
                     case 6:
-                        e_5_1 = _f.sent();
-                        e_5 = { error: e_5_1 };
+                        e_6_1 = _f.sent();
+                        e_6 = { error: e_6_1 };
                         return [3 /*break*/, 12];
                     case 7:
                         _f.trys.push([7, , 10, 11]);
@@ -850,7 +932,7 @@ var AsyncCollection = /** @class */ (function () {
                         _f.label = 9;
                     case 9: return [3 /*break*/, 11];
                     case 10:
-                        if (e_5) throw e_5.error;
+                        if (e_6) throw e_6.error;
                         return [7 /*endfinally*/];
                     case 11: return [7 /*endfinally*/];
                     case 12: return [2 /*return*/, output];
@@ -1037,6 +1119,8 @@ var DataStoreState;
     DataStoreState["Stopping"] = "Stopping";
     DataStoreState["Clearing"] = "Clearing";
 })(DataStoreState || (DataStoreState = {}));
+// TODO: How can we get rid of the non-null assertions?
+// https://github.com/aws-amplify/amplify-js/pull/10477/files#r1007363485
 var DataStore = /** @class */ (function () {
     function DataStore() {
         var _this = this;
@@ -1100,8 +1184,8 @@ var DataStore = /** @class */ (function () {
         /**
          * If not already done:
          * 1. Attaches and initializes storage.
-         * 1. Loads the schema and records metadata.
-         * 1. If `this.amplifyConfig.aws_appsync_graphqlEndpoint` contains a URL,
+         * 2. Loads the schema and records metadata.
+         * 3. If `this.amplifyConfig.aws_appsync_graphqlEndpoint` contains a URL,
          * attaches a sync engine, starts it, and subscribes.
          */
         this.start = function () { return tslib_1.__awaiter(_this, void 0, void 0, function () {
@@ -1246,7 +1330,7 @@ var DataStore = /** @class */ (function () {
                                     seedPredicate = next_1.recursivePredicateFor({
                                         builder: modelConstructor,
                                         schema: modelDefinition,
-                                        pkField: getModelPKFieldName(modelConstructor),
+                                        pkField: util_1.extractPrimaryKeyFieldNames(modelDefinition),
                                     });
                                     predicate = next_1.internals(identifierOrCriteria(seedPredicate));
                                     return [4 /*yield*/, predicate.fetch(this.storage)];
@@ -1296,8 +1380,8 @@ var DataStore = /** @class */ (function () {
                                         pkField: util_1.extractPrimaryKeyFieldNames(modelDefinition),
                                     };
                                     return [4 /*yield*/, this.storage.runExclusive(function (s) { return tslib_1.__awaiter(_this, void 0, void 0, function () {
-                                            var nonHasManyRelationships, nonHasManyRelationships_1, nonHasManyRelationships_1_1, relationship, queryObject, related, e_6_1;
-                                            var e_6, _a;
+                                            var nonHasManyRelationships, nonHasManyRelationships_1, nonHasManyRelationships_1_1, relationship, queryObject, related, e_7_1;
+                                            var e_7, _a;
                                             var _b;
                                             return tslib_1.__generator(this, function (_c) {
                                                 switch (_c.label) {
@@ -1330,14 +1414,14 @@ var DataStore = /** @class */ (function () {
                                                         return [3 /*break*/, 2];
                                                     case 5: return [3 /*break*/, 8];
                                                     case 6:
-                                                        e_6_1 = _c.sent();
-                                                        e_6 = { error: e_6_1 };
+                                                        e_7_1 = _c.sent();
+                                                        e_7 = { error: e_7_1 };
                                                         return [3 /*break*/, 8];
                                                     case 7:
                                                         try {
                                                             if (nonHasManyRelationships_1_1 && !nonHasManyRelationships_1_1.done && (_a = nonHasManyRelationships_1.return)) _a.call(nonHasManyRelationships_1);
                                                         }
-                                                        finally { if (e_6) throw e_6.error; }
+                                                        finally { if (e_7) throw e_7.error; }
                                                         return [7 /*endfinally*/];
                                                     case 8: return [2 /*return*/];
                                                 }