@aws-amplify/datastore 3.14.1-unstable.2 → 3.14.1

package/lib/datastore/datastore.js

@@ -93,9 +93,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 var api_1 = __importDefault(require("@aws-amplify/api"));
-var core_1 = require("@aws-amplify/core");
 var auth_1 = require("@aws-amplify/auth");
 var cache_1 = __importDefault(require("@aws-amplify/cache"));
+var core_1 = require("@aws-amplify/core");
 var immer_1 = require("immer");
 var uuid_1 = require("uuid");
 var zen_observable_ts_1 = __importDefault(require("zen-observable-ts"));
@@ -209,10 +209,14 @@ var initSchema = function (userSchema) {
     return userClasses;
 };
 exports.initSchema = initSchema;
-/* Checks if the schema has been initialized by initSchema().
+/**
+ * Throws an exception if the schema has *not* been initialized
+ * by `initSchema()`.
+ *
+ * **To be called before trying to access schema.**
  *
- * Call this function before accessing schema.
- * Currently this only needs to be called in start() and clear() because all other functions will call start first.
+ * Currently this only needs to be called in `start()` and `clear()` because
+ * all other functions will call start first.
  */
 var checkSchemaInitialized = function () {
     if (schema === undefined) {
@@ -236,6 +240,11 @@ var createTypeClasses = function (namespace) {
     });
     return classes;
 };
+/**
+ * Collection of instantiated models to allow storage of metadata apart from
+ * the model visible to the consuming app -- in case the app doesn't have
+ * metadata fields (_version, _deleted, etc.) exposed on the model itself.
+ */
 var instancesMetadata = new WeakSet();
 function modelInstanceCreator(modelConstructor, init) {
     instancesMetadata.add(init);
@@ -554,6 +563,18 @@ function getModelConstructorByModelName(namespaceName, modelName) {
         throw new Error(msg);
     }
 }
+/**
+ * Queries the DataStore metadata tables to see if they are the expected
+ * version. If not, clobbers the whole DB. If so, leaves them alone.
+ * Otherwise, simply writes the schema version.
+ *
+ * SIDE EFFECT:
+ * 1. Creates a transaction
+ * 1. Updates data.
+ *
+ * @param storage Storage adapter containing the metadata.
+ * @param version The expected schema version.
+ */
 function checkSchemaVersion(storage, version) {
     return __awaiter(this, void 0, void 0, function () {
         var Setting, modelDefinition;
@@ -636,6 +657,14 @@ function getNamespace() {
     };
     return namespace;
 }
+var DataStoreState;
+(function (DataStoreState) {
+    DataStoreState["NotRunning"] = "Not Running";
+    DataStoreState["Starting"] = "Starting";
+    DataStoreState["Running"] = "Running";
+    DataStoreState["Stopping"] = "Stopping";
+    DataStoreState["Clearing"] = "Clearing";
+})(DataStoreState || (DataStoreState = {}));
 var DataStore = /** @class */ (function () {
     function DataStore() {
         var _this = this;
@@ -651,168 +680,235 @@ var DataStore = /** @class */ (function () {
             API: this.API,
             Cache: this.Cache,
         };
+        /**
+         * **IMPORTANT!**
+         *
+         * Accumulator for background things that can **and MUST** be called when
+         * DataStore stops.
+         *
+         * These jobs **MUST** be *idempotent promises* that resolve ONLY
+         * once the intended jobs are completely finished and/or otherwise destroyed
+         * and cleaned up with ZERO outstanding:
+         *
+         * 1. side effects (e.g., state changes)
+         * 1. callbacks
+         * 1. subscriptions
+         * 1. calls to storage
+         * 1. *etc.*
+         *
+         * Methods that create pending promises, subscriptions, callbacks, or any
+         * type of side effect **MUST** be registered with the manager. And, a new
+         * manager must be created after each `exit()`.
+         *
+         * Failure to comply will put DataStore into a highly unpredictable state
+         * when it needs to stop or clear -- which occurs when restarting with new
+         * sync expressions, during testing, and potentially during app code
+         * recovery handling, etc..
+         *
+         * It is up to the discretion of each disposer whether to wait for job
+         * completion or to cancel operations and issue failures *as long as the
+         * disposer returns in a reasonable amount of time.*
+         *
+         * (Reasonable = *seconds*, not minutes.)
+         */
+        this.runningProcesses = new core_1.BackgroundProcessManager();
+        /**
+         * Indicates what state DataStore is in.
+         *
+         * Not [yet?] used for actual state management; but for messaging
+         * when errors occur, to help troubleshoot.
+         */
+        this.state = DataStoreState.NotRunning;
+        /**
+         * 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,
+         * attaches a sync engine, starts it, and subscribes.
+         */
         this.start = function () { return __awaiter(_this, void 0, void 0, function () {
-            var aws_appsync_graphqlEndpoint, _a, fullSyncIntervalInMilliseconds;
             var _this = this;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        if (!(this.initialized === undefined)) return [3 /*break*/, 1];
-                        logger.debug('Starting DataStore');
-                        this.initialized = new Promise(function (res, rej) {
-                            _this.initResolve = res;
-                            _this.initReject = rej;
-                        });
-                        return [3 /*break*/, 3];
-                    case 1: return [4 /*yield*/, this.initialized];
-                    case 2:
-                        _b.sent();
-                        return [2 /*return*/];
-                    case 3:
-                        this.storage = new storage_1.ExclusiveStorage(schema, namespaceResolver, getModelConstructorByModelName, modelInstanceCreator, this.storageAdapter, this.sessionId);
-                        return [4 /*yield*/, this.storage.init()];
-                    case 4:
-                        _b.sent();
-                        checkSchemaInitialized();
-                        return [4 /*yield*/, checkSchemaVersion(this.storage, schema.version)];
-                    case 5:
-                        _b.sent();
-                        aws_appsync_graphqlEndpoint = this.amplifyConfig.aws_appsync_graphqlEndpoint;
-                        if (!aws_appsync_graphqlEndpoint) return [3 /*break*/, 7];
-                        logger.debug('GraphQL endpoint available', aws_appsync_graphqlEndpoint);
-                        _a = this;
-                        return [4 /*yield*/, this.processSyncExpressions()];
-                    case 6:
-                        _a.syncPredicates = _b.sent();
-                        this.sync = new sync_1.SyncEngine(schema, namespaceResolver, exports.syncClasses, userClasses, this.storage, modelInstanceCreator, this.conflictHandler, this.errorHandler, this.syncPredicates, this.amplifyConfig, this.authModeStrategy, this.amplifyContext);
-                        fullSyncIntervalInMilliseconds = this.fullSyncInterval * 1000 * 60;
-                        syncSubscription = this.sync
-                            .start({ fullSyncInterval: fullSyncIntervalInMilliseconds })
-                            .subscribe({
-                            next: function (_a) {
-                                var type = _a.type, data = _a.data;
-                                // In Node, we need to wait for queries to be synced to prevent returning empty arrays.
-                                // In the Browser, we can begin returning data once subscriptions are in place.
-                                var readyType = isNode
-                                    ? sync_1.ControlMessage.SYNC_ENGINE_SYNC_QUERIES_READY
-                                    : sync_1.ControlMessage.SYNC_ENGINE_STORAGE_SUBSCRIBED;
-                                if (type === readyType) {
-                                    _this.initResolve();
-                                }
-                                core_1.Hub.dispatch('datastore', {
-                                    event: type,
-                                    data: data,
-                                });
-                            },
-                            error: function (err) {
-                                logger.warn('Sync error', err);
-                                _this.initReject();
-                            },
-                        });
-                        return [3 /*break*/, 8];
-                    case 7:
-                        logger.warn("Data won't be synchronized. No GraphQL endpoint configured. Did you forget `Amplify.configure(awsconfig)`?", {
-                            config: this.amplifyConfig,
+            return __generator(this, function (_a) {
+                return [2 /*return*/, this.runningProcesses
+                        .add(function () { return __awaiter(_this, void 0, void 0, function () {
+                        var aws_appsync_graphqlEndpoint, _a, fullSyncIntervalInMilliseconds;
+                        var _this = this;
+                        return __generator(this, function (_b) {
+                            switch (_b.label) {
+                                case 0:
+                                    this.state = DataStoreState.Starting;
+                                    if (!(this.initialized === undefined)) return [3 /*break*/, 1];
+                                    logger.debug('Starting DataStore');
+                                    this.initialized = new Promise(function (res, rej) {
+                                        _this.initResolve = res;
+                                        _this.initReject = rej;
+                                    });
+                                    return [3 /*break*/, 3];
+                                case 1: return [4 /*yield*/, this.initialized];
+                                case 2:
+                                    _b.sent();
+                                    return [2 /*return*/];
+                                case 3:
+                                    this.storage = new storage_1.ExclusiveStorage(schema, namespaceResolver, getModelConstructorByModelName, modelInstanceCreator, this.storageAdapter, this.sessionId);
+                                    return [4 /*yield*/, this.storage.init()];
+                                case 4:
+                                    _b.sent();
+                                    checkSchemaInitialized();
+                                    return [4 /*yield*/, checkSchemaVersion(this.storage, schema.version)];
+                                case 5:
+                                    _b.sent();
+                                    aws_appsync_graphqlEndpoint = this.amplifyConfig.aws_appsync_graphqlEndpoint;
+                                    if (!aws_appsync_graphqlEndpoint) return [3 /*break*/, 7];
+                                    logger.debug('GraphQL endpoint available', aws_appsync_graphqlEndpoint);
+                                    _a = this;
+                                    return [4 /*yield*/, this.processSyncExpressions()];
+                                case 6:
+                                    _a.syncPredicates = _b.sent();
+                                    this.sync = new sync_1.SyncEngine(schema, namespaceResolver, exports.syncClasses, userClasses, this.storage, modelInstanceCreator, this.conflictHandler, this.errorHandler, this.syncPredicates, this.amplifyConfig, this.authModeStrategy, this.amplifyContext, this.connectivityMonitor);
+                                    fullSyncIntervalInMilliseconds = this.fullSyncInterval * 1000 * 60;
+                                    syncSubscription = this.sync
+                                        .start({ fullSyncInterval: fullSyncIntervalInMilliseconds })
+                                        .subscribe({
+                                        next: function (_a) {
+                                            var type = _a.type, data = _a.data;
+                                            // In Node, we need to wait for queries to be synced to prevent returning empty arrays.
+                                            // In the Browser, we can begin returning data once subscriptions are in place.
+                                            var readyType = isNode
+                                                ? sync_1.ControlMessage.SYNC_ENGINE_SYNC_QUERIES_READY
+                                                : sync_1.ControlMessage.SYNC_ENGINE_STORAGE_SUBSCRIBED;
+                                            if (type === readyType) {
+                                                _this.initResolve();
+                                            }
+                                            core_1.Hub.dispatch('datastore', {
+                                                event: type,
+                                                data: data,
+                                            });
+                                        },
+                                        error: function (err) {
+                                            logger.warn('Sync error', err);
+                                            _this.initReject();
+                                        },
+                                    });
+                                    return [3 /*break*/, 8];
+                                case 7:
+                                    logger.warn("Data won't be synchronized. No GraphQL endpoint configured. Did you forget `Amplify.configure(awsconfig)`?", {
+                                        config: this.amplifyConfig,
+                                    });
+                                    this.initResolve();
+                                    _b.label = 8;
+                                case 8: return [4 /*yield*/, this.initialized];
+                                case 9:
+                                    _b.sent();
+                                    this.state = DataStoreState.Running;
+                                    return [2 /*return*/];
+                            }
                         });
-                        this.initResolve();
-                        _b.label = 8;
-                    case 8: return [4 /*yield*/, this.initialized];
-                    case 9:
-                        _b.sent();
-                        return [2 /*return*/];
-                }
+                    }); }, 'datastore start')
+                        .catch(this.handleAddProcError('DataStore.start()'))];
             });
         }); };
         this.query = function (modelConstructor, identifierOrCriteria, paginationProducer) { return __awaiter(_this, void 0, void 0, function () {
-            var msg, modelDefinition, keyFields, predicate, msg, pagination, result, returnOne;
+            var _this = this;
             return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.start()];
-                    case 1:
-                        _a.sent();
-                        //#region Input validation
-                        if (!isValidModelConstructor(modelConstructor)) {
-                            msg = 'Constructor is not for a valid model';
-                            logger.error(msg, { modelConstructor: modelConstructor });
-                            throw new Error(msg);
-                        }
-                        if (typeof identifierOrCriteria === 'string') {
-                            if (paginationProducer !== undefined) {
-                                logger.warn('Pagination is ignored when querying by id');
-                            }
-                        }
-                        modelDefinition = getModelDefinition(modelConstructor);
-                        keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
-                        if (isQueryOne(identifierOrCriteria)) {
-                            if (keyFields.length > 1) {
-                                msg = util_1.errorMessages.queryByPkWithCompositeKeyPresent;
-                                logger.error(msg, { keyFields: keyFields });
-                                throw new Error(msg);
-                            }
-                            predicate = predicates_1.ModelPredicateCreator.createForSingleField(modelDefinition, keyFields[0], identifierOrCriteria);
-                        }
-                        else {
-                            // Object is being queried using object literal syntax
-                            if (types_1.isIdentifierObject(identifierOrCriteria, modelDefinition)) {
-                                predicate = predicates_1.ModelPredicateCreator.createForPk(modelDefinition, identifierOrCriteria);
-                            }
-                            else if (predicates_1.isPredicatesAll(identifierOrCriteria)) {
-                                // Predicates.ALL means "all records", so no predicate (undefined)
-                                predicate = undefined;
-                            }
-                            else {
-                                predicate = predicates_1.ModelPredicateCreator.createFromExisting(modelDefinition, identifierOrCriteria);
+                return [2 /*return*/, this.runningProcesses
+                        .add(function () { return __awaiter(_this, void 0, void 0, function () {
+                        var msg, modelDefinition, keyFields, predicate, msg, pagination, result, returnOne;
+                        return __generator(this, function (_a) {
+                            switch (_a.label) {
+                                case 0: return [4 /*yield*/, this.start()];
+                                case 1:
+                                    _a.sent();
+                                    //#region Input validation
+                                    if (!isValidModelConstructor(modelConstructor)) {
+                                        msg = 'Constructor is not for a valid model';
+                                        logger.error(msg, { modelConstructor: modelConstructor });
+                                        throw new Error(msg);
+                                    }
+                                    if (typeof identifierOrCriteria === 'string') {
+                                        if (paginationProducer !== undefined) {
+                                            logger.warn('Pagination is ignored when querying by id');
+                                        }
+                                    }
+                                    modelDefinition = getModelDefinition(modelConstructor);
+                                    keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
+                                    if (isQueryOne(identifierOrCriteria)) {
+                                        if (keyFields.length > 1) {
+                                            msg = util_1.errorMessages.queryByPkWithCompositeKeyPresent;
+                                            logger.error(msg, { keyFields: keyFields });
+                                            throw new Error(msg);
+                                        }
+                                        predicate = predicates_1.ModelPredicateCreator.createForSingleField(modelDefinition, keyFields[0], identifierOrCriteria);
+                                    }
+                                    else {
+                                        // Object is being queried using object literal syntax
+                                        if (types_1.isIdentifierObject(identifierOrCriteria, modelDefinition)) {
+                                            predicate = predicates_1.ModelPredicateCreator.createForPk(modelDefinition, identifierOrCriteria);
+                                        }
+                                        else if (predicates_1.isPredicatesAll(identifierOrCriteria)) {
+                                            // Predicates.ALL means "all records", so no predicate (undefined)
+                                            predicate = undefined;
+                                        }
+                                        else {
+                                            predicate = predicates_1.ModelPredicateCreator.createFromExisting(modelDefinition, identifierOrCriteria);
+                                        }
+                                    }
+                                    pagination = this.processPagination(modelDefinition, paginationProducer);
+                                    //#endregion
+                                    logger.debug('params ready', {
+                                        modelConstructor: modelConstructor,
+                                        predicate: predicates_1.ModelPredicateCreator.getPredicates(predicate, false),
+                                        pagination: __assign(__assign({}, pagination), { sort: predicates_1.ModelSortPredicateCreator.getPredicates(pagination && pagination.sort, false) }),
+                                    });
+                                    return [4 /*yield*/, this.storage.query(modelConstructor, predicate, pagination)];
+                                case 2:
+                                    result = _a.sent();
+                                    returnOne = isQueryOne(identifierOrCriteria) ||
+                                        types_1.isIdentifierObject(identifierOrCriteria, modelDefinition);
+                                    return [2 /*return*/, returnOne ? result[0] : result];
                             }
-                        }
-                        pagination = this.processPagination(modelDefinition, paginationProducer);
-                        //#endregion
-                        logger.debug('params ready', {
-                            modelConstructor: modelConstructor,
-                            predicate: predicates_1.ModelPredicateCreator.getPredicates(predicate, false),
-                            pagination: __assign(__assign({}, pagination), { sort: predicates_1.ModelSortPredicateCreator.getPredicates(pagination && pagination.sort, false) }),
                         });
-                        return [4 /*yield*/, this.storage.query(modelConstructor, predicate, pagination)];
-                    case 2:
-                        result = _a.sent();
-                        returnOne = isQueryOne(identifierOrCriteria) ||
-                            types_1.isIdentifierObject(identifierOrCriteria, modelDefinition);
-                        return [2 /*return*/, returnOne ? result[0] : result];
-                }
+                    }); }, 'datastore query')
+                        .catch(this.handleAddProcError('DataStore.query()'))];
             });
         }); };
         this.save = function (model, condition) { return __awaiter(_this, void 0, void 0, function () {
-            var patchesTuple, modelConstructor, msg, modelDefinition, producedCondition, _a, savedModel;
             var _this = this;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0: return [4 /*yield*/, this.start()];
-                    case 1:
-                        _b.sent();
-                        patchesTuple = modelPatchesMap.get(model);
-                        modelConstructor = model
-                            ? model.constructor
-                            : undefined;
-                        if (!isValidModelConstructor(modelConstructor)) {
-                            msg = 'Object is not an instance of a valid model';
-                            logger.error(msg, { model: model });
-                            throw new Error(msg);
-                        }
-                        modelDefinition = getModelDefinition(modelConstructor);
-                        producedCondition = predicates_1.ModelPredicateCreator.createFromExisting(modelDefinition, condition);
-                        return [4 /*yield*/, this.storage.runExclusive(function (s) { return __awaiter(_this, void 0, void 0, function () {
-                                return __generator(this, function (_a) {
-                                    switch (_a.label) {
-                                        case 0: return [4 /*yield*/, s.save(model, producedCondition, undefined, patchesTuple)];
-                                        case 1:
-                                            _a.sent();
-                                            return [2 /*return*/, s.query(modelConstructor, predicates_1.ModelPredicateCreator.createForPk(modelDefinition, model))];
+            return __generator(this, function (_a) {
+                return [2 /*return*/, this.runningProcesses
+                        .add(function () { return __awaiter(_this, void 0, void 0, function () {
+                        var patchesTuple, modelConstructor, msg, modelDefinition, producedCondition, _a, savedModel;
+                        var _this = this;
+                        return __generator(this, function (_b) {
+                            switch (_b.label) {
+                                case 0: return [4 /*yield*/, this.start()];
+                                case 1:
+                                    _b.sent();
+                                    patchesTuple = modelPatchesMap.get(model);
+                                    modelConstructor = model ? model.constructor : undefined;
+                                    if (!isValidModelConstructor(modelConstructor)) {
+                                        msg = 'Object is not an instance of a valid model';
+                                        logger.error(msg, { model: model });
+                                        throw new Error(msg);
                                     }
-                                });
-                            }); })];
-                    case 2:
-                        _a = __read.apply(void 0, [_b.sent(), 1]), savedModel = _a[0];
-                        return [2 /*return*/, savedModel];
-                }
+                                    modelDefinition = getModelDefinition(modelConstructor);
+                                    producedCondition = predicates_1.ModelPredicateCreator.createFromExisting(modelDefinition, condition);
+                                    return [4 /*yield*/, this.storage.runExclusive(function (s) { return __awaiter(_this, void 0, void 0, function () {
+                                            return __generator(this, function (_a) {
+                                                switch (_a.label) {
+                                                    case 0: return [4 /*yield*/, s.save(model, producedCondition, undefined, patchesTuple)];
+                                                    case 1:
+                                                        _a.sent();
+                                                        return [2 /*return*/, s.query(modelConstructor, predicates_1.ModelPredicateCreator.createForPk(modelDefinition, model))];
+                                                }
+                                            });
+                                        }); })];
+                                case 2:
+                                    _a = __read.apply(void 0, [_b.sent(), 1]), savedModel = _a[0];
+                                    return [2 /*return*/, savedModel];
+                            }
+                        });
+                    }); }, 'datastore save')
+                        .catch(this.handleAddProcError('DataStore.save()'))];
             });
         }); };
         this.setConflictHandler = function (config) {
@@ -842,83 +938,91 @@ var DataStore = /** @class */ (function () {
             return _this.errorHandler || defaultErrorHandler;
         };
         this.delete = function (modelOrConstructor, identifierOrCriteria) { return __awaiter(_this, void 0, void 0, function () {
-            var condition, msg, modelConstructor, msg, modelDefinition, keyFields, msg, msg, _a, deleted, model, modelConstructor, msg, modelDefinition, pkPredicate, msg, _b, _c, deleted;
-            return __generator(this, function (_d) {
-                switch (_d.label) {
-                    case 0: return [4 /*yield*/, this.start()];
-                    case 1:
-                        _d.sent();
-                        if (!modelOrConstructor) {
-                            msg = 'Model or Model Constructor required';
-                            logger.error(msg, { modelOrConstructor: modelOrConstructor });
-                            throw new Error(msg);
-                        }
-                        if (!isValidModelConstructor(modelOrConstructor)) return [3 /*break*/, 3];
-                        modelConstructor = modelOrConstructor;
-                        if (!identifierOrCriteria) {
-                            msg = 'Id to delete or criteria required. Do you want to delete all? Pass Predicates.ALL';
-                            logger.error(msg, { identifierOrCriteria: identifierOrCriteria });
-                            throw new Error(msg);
-                        }
-                        modelDefinition = getModelDefinition(modelConstructor);
-                        if (typeof identifierOrCriteria === 'string') {
-                            keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
-                            if (keyFields.length > 1) {
-                                msg = util_1.errorMessages.deleteByPkWithCompositeKeyPresent;
-                                logger.error(msg, { keyFields: keyFields });
-                                throw new Error(msg);
-                            }
-                            condition = predicates_1.ModelPredicateCreator.createForSingleField(getModelDefinition(modelConstructor), keyFields[0], identifierOrCriteria);
-                        }
-                        else {
-                            if (types_1.isIdentifierObject(identifierOrCriteria, modelDefinition)) {
-                                condition = predicates_1.ModelPredicateCreator.createForPk(modelDefinition, identifierOrCriteria);
-                            }
-                            else {
-                                condition = predicates_1.ModelPredicateCreator.createFromExisting(modelDefinition, 
-                                /**
-                                 * idOrCriteria is always a ProducerModelPredicate<T>, never a symbol.
-                                 * The symbol is used only for typing purposes. e.g. see Predicates.ALL
-                                 */
-                                identifierOrCriteria);
-                            }
-                            if (!condition || !predicates_1.ModelPredicateCreator.isValidPredicate(condition)) {
-                                msg = 'Criteria required. Do you want to delete all? Pass Predicates.ALL';
-                                logger.error(msg, { condition: condition });
-                                throw new Error(msg);
-                            }
-                        }
-                        return [4 /*yield*/, this.storage.delete(modelConstructor, condition)];
-                    case 2:
-                        _a = __read.apply(void 0, [_d.sent(), 1]), deleted = _a[0];
-                        return [2 /*return*/, deleted];
-                    case 3:
-                        model = modelOrConstructor;
-                        modelConstructor = Object.getPrototypeOf(model || {})
-                            .constructor;
-                        if (!isValidModelConstructor(modelConstructor)) {
-                            msg = 'Object is not an instance of a valid model';
-                            logger.error(msg, { model: model });
-                            throw new Error(msg);
-                        }
-                        modelDefinition = getModelDefinition(modelConstructor);
-                        pkPredicate = predicates_1.ModelPredicateCreator.createForPk(modelDefinition, model);
-                        if (identifierOrCriteria) {
-                            if (typeof identifierOrCriteria !== 'function') {
-                                msg = 'Invalid criteria';
-                                logger.error(msg, { identifierOrCriteria: identifierOrCriteria });
-                                throw new Error(msg);
+            var _this = this;
+            return __generator(this, function (_a) {
+                return [2 /*return*/, this.runningProcesses
+                        .add(function () { return __awaiter(_this, void 0, void 0, function () {
+                        var condition, msg, modelConstructor, msg, modelDefinition, keyFields, msg, msg, _a, deleted, model, modelConstructor, msg, modelDefinition, pkPredicate, msg, _b, _c, deleted;
+                        return __generator(this, function (_d) {
+                            switch (_d.label) {
+                                case 0: return [4 /*yield*/, this.start()];
+                                case 1:
+                                    _d.sent();
+                                    if (!modelOrConstructor) {
+                                        msg = 'Model or Model Constructor required';
+                                        logger.error(msg, { modelOrConstructor: modelOrConstructor });
+                                        throw new Error(msg);
+                                    }
+                                    if (!isValidModelConstructor(modelOrConstructor)) return [3 /*break*/, 3];
+                                    modelConstructor = modelOrConstructor;
+                                    if (!identifierOrCriteria) {
+                                        msg = 'Id to delete or criteria required. Do you want to delete all? Pass Predicates.ALL';
+                                        logger.error(msg, { identifierOrCriteria: identifierOrCriteria });
+                                        throw new Error(msg);
+                                    }
+                                    modelDefinition = getModelDefinition(modelConstructor);
+                                    if (typeof identifierOrCriteria === 'string') {
+                                        keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
+                                        if (keyFields.length > 1) {
+                                            msg = util_1.errorMessages.deleteByPkWithCompositeKeyPresent;
+                                            logger.error(msg, { keyFields: keyFields });
+                                            throw new Error(msg);
+                                        }
+                                        condition = predicates_1.ModelPredicateCreator.createForSingleField(getModelDefinition(modelConstructor), keyFields[0], identifierOrCriteria);
+                                    }
+                                    else {
+                                        if (types_1.isIdentifierObject(identifierOrCriteria, modelDefinition)) {
+                                            condition = predicates_1.ModelPredicateCreator.createForPk(modelDefinition, identifierOrCriteria);
+                                        }
+                                        else {
+                                            condition = predicates_1.ModelPredicateCreator.createFromExisting(modelDefinition, 
+                                            /**
+                                             * idOrCriteria is always a ProducerModelPredicate<T>, never a symbol.
+                                             * The symbol is used only for typing purposes. e.g. see Predicates.ALL
+                                             */
+                                            identifierOrCriteria);
+                                        }
+                                        if (!condition ||
+                                            !predicates_1.ModelPredicateCreator.isValidPredicate(condition)) {
+                                            msg = 'Criteria required. Do you want to delete all? Pass Predicates.ALL';
+                                            logger.error(msg, { condition: condition });
+                                            throw new Error(msg);
+                                        }
+                                    }
+                                    return [4 /*yield*/, this.storage.delete(modelConstructor, condition)];
+                                case 2:
+                                    _a = __read.apply(void 0, [_d.sent(), 1]), deleted = _a[0];
+                                    return [2 /*return*/, deleted];
+                                case 3:
+                                    model = modelOrConstructor;
+                                    modelConstructor = Object.getPrototypeOf(model || {})
+                                        .constructor;
+                                    if (!isValidModelConstructor(modelConstructor)) {
+                                        msg = 'Object is not an instance of a valid model';
+                                        logger.error(msg, { model: model });
+                                        throw new Error(msg);
+                                    }
+                                    modelDefinition = getModelDefinition(modelConstructor);
+                                    pkPredicate = predicates_1.ModelPredicateCreator.createForPk(modelDefinition, model);
+                                    if (identifierOrCriteria) {
+                                        if (typeof identifierOrCriteria !== 'function') {
+                                            msg = 'Invalid criteria';
+                                            logger.error(msg, { identifierOrCriteria: identifierOrCriteria });
+                                            throw new Error(msg);
+                                        }
+                                        condition = identifierOrCriteria(pkPredicate);
+                                    }
+                                    else {
+                                        condition = pkPredicate;
+                                    }
+                                    return [4 /*yield*/, this.storage.delete(model, condition)];
+                                case 4:
+                                    _b = __read.apply(void 0, [_d.sent(), 1]), _c = __read(_b[0], 1), deleted = _c[0];
+                                    return [2 /*return*/, deleted];
                             }
-                            condition = identifierOrCriteria(pkPredicate);
-                        }
-                        else {
-                            condition = pkPredicate;
-                        }
-                        return [4 /*yield*/, this.storage.delete(model, condition)];
-                    case 4:
-                        _b = __read.apply(void 0, [_d.sent(), 1]), _c = __read(_b[0], 1), deleted = _c[0];
-                        return [2 /*return*/, deleted];
-                }
+                        });
+                    }); }, 'datastore delete')
+                        .catch(this.handleAddProcError('DataStore.delete()'))];
             });
         }); };
         this.observe = function (modelOrConstructor, identifierOrCriteria) {
@@ -979,7 +1083,8 @@ var DataStore = /** @class */ (function () {
             }
             return new zen_observable_ts_1.default(function (observer) {
                 var handle;
-                (function () { return __awaiter(_this, void 0, void 0, function () {
+                _this.runningProcesses
+                    .add(function () { return __awaiter(_this, void 0, void 0, function () {
                     var _this = this;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -995,39 +1100,52 @@ var DataStore = /** @class */ (function () {
                                     return namespaceResolver(model) === util_1.USER;
                                 })
                                     .subscribe({
-                                    next: function (item) { return __awaiter(_this, void 0, void 0, function () {
-                                        var message, modelDefinition, keyFields, primaryKeysAndValues, freshElement;
-                                        return __generator(this, function (_a) {
-                                            switch (_a.label) {
-                                                case 0:
-                                                    message = item;
-                                                    if (!(item.opType !== 'DELETE')) return [3 /*break*/, 2];
-                                                    modelDefinition = getModelDefinition(item.model);
-                                                    keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
-                                                    primaryKeysAndValues = util_1.extractPrimaryKeysAndValues(item.element, keyFields);
-                                                    return [4 /*yield*/, this.query(item.model, primaryKeysAndValues)];
-                                                case 1:
-                                                    freshElement = _a.sent();
-                                                    message = __assign(__assign({}, message), { element: freshElement });
-                                                    _a.label = 2;
-                                                case 2:
-                                                    observer.next(message);
-                                                    return [2 /*return*/];
-                                            }
-                                        });
-                                    }); },
+                                    next: function (item) {
+                                        return _this.runningProcesses.isOpen &&
+                                            _this.runningProcesses.add(function () { return __awaiter(_this, void 0, void 0, function () {
+                                                var message, modelDefinition, keyFields, primaryKeysAndValues, freshElement;
+                                                return __generator(this, function (_a) {
+                                                    switch (_a.label) {
+                                                        case 0:
+                                                            message = item;
+                                                            if (!(item.opType !== 'DELETE')) return [3 /*break*/, 2];
+                                                            modelDefinition = getModelDefinition(item.model);
+                                                            keyFields = util_1.extractPrimaryKeyFieldNames(modelDefinition);
+                                                            primaryKeysAndValues = util_1.extractPrimaryKeysAndValues(item.element, keyFields);
+                                                            return [4 /*yield*/, this.query(item.model, primaryKeysAndValues)];
+                                                        case 1:
+                                                            freshElement = _a.sent();
+                                                            message = __assign(__assign({}, message), { element: freshElement });
+                                                            _a.label = 2;
+                                                        case 2:
+                                                            observer.next(message);
+                                                            return [2 /*return*/];
+                                                    }
+                                                });
+                                            }); }, 'datastore observe message handler');
+                                    },
                                     error: function (err) { return observer.error(err); },
                                     complete: function () { return observer.complete(); },
                                 });
                                 return [2 /*return*/];
                         }
                     });
-                }); })();
-                return function () {
-                    if (handle) {
-                        handle.unsubscribe();
-                    }
-                };
+                }); }, 'datastore observe observable initialization')
+                    .catch(_this.handleAddProcError('DataStore.observe()'))
+                    .catch(function (error) {
+                    observer.error(error);
+                });
+                // better than no cleaner, but if the subscriber is handling the
+                // complete() message async and not registering with the context,
+                // this will still be problematic.
+                return _this.runningProcesses.addCleaner(function () { return __awaiter(_this, void 0, void 0, function () {
+                    return __generator(this, function (_a) {
+                        if (handle) {
+                            handle.unsubscribe();
+                        }
+                        return [2 /*return*/];
+                    });
+                }); }, 'DataStore.observe() cleanup');
             });
         };
         this.observeQuery = function (model, criteria, options) {
@@ -1076,7 +1194,8 @@ var DataStore = /** @class */ (function () {
                 }
                 var _a = predicates_1.ModelPredicateCreator.getPredicates(predicate, false) || {}, predicates = _a.predicates, predicateGroupType = _a.type;
                 var hasPredicate = !!predicates;
-                (function () { return __awaiter(_this, void 0, void 0, function () {
+                _this.runningProcesses
+                    .add(function () { return __awaiter(_this, void 0, void 0, function () {
                     var err_1;
                     var _this = this;
                     return __generator(this, function (_a) {
@@ -1126,7 +1245,8 @@ var DataStore = /** @class */ (function () {
                                         itemsChanged.set(idOrPk, element);
                                     }
                                     var isSynced = (_c = (_b = _this.sync) === null || _b === void 0 ? void 0 : _b.getModelSyncedStatus(model)) !== null && _c !== void 0 ? _c : false;
-                                    var limit = itemsChanged.size - deletedItemIds.length >= _this.syncPageSize;
+                                    var limit = itemsChanged.size - deletedItemIds.length >=
+                                        _this.syncPageSize;
                                     if (limit || isSynced) {
                                         limitTimerRace.resolve();
                                     }
@@ -1143,7 +1263,11 @@ var DataStore = /** @class */ (function () {
                             case 3: return [2 /*return*/];
                         }
                     });
-                }); })();
+                }); }, 'datastore observequery startup')
+                    .catch(_this.handleAddProcError('DataStore.observeQuery()'))
+                    .catch(function (error) {
+                    observer.error(error);
+                });
                 /**
                  * Combines the `items`, `itemsChanged`, and `deletedItemIds` collections into
                  * a snapshot in the form of `{ items: T[], isSynced: boolean}`.
@@ -1179,7 +1303,8 @@ var DataStore = /** @class */ (function () {
                  * @param snapshot The generated items data to emit.
                  */
                 var emitSnapshot = function (snapshot) {
-                    // send the generated snapshot to the primary subscription
+                    // send the generated snapshot to the primary subscription.
+                    // NOTE: This observer's handler *could* be async ...
                     observer.next(snapshot);
                     // reset the changed items sets
                     itemsChanged.clear();
@@ -1215,15 +1340,18 @@ var DataStore = /** @class */ (function () {
                     if (event === sync_1.ControlMessage.SYNC_ENGINE_MODEL_SYNCED &&
                         ((_b = data === null || data === void 0 ? void 0 : data.model) === null || _b === void 0 ? void 0 : _b.name) === model.name) {
                         generateAndEmitSnapshot();
-                        core_1.Hub.remove('api', hubCallback);
+                        core_1.Hub.remove('datastore', hubCallback);
                     }
                 };
                 core_1.Hub.listen('datastore', hubCallback);
-                return function () {
-                    if (handle) {
-                        handle.unsubscribe();
-                    }
-                };
+                return _this.runningProcesses.addCleaner(function () { return __awaiter(_this, void 0, void 0, function () {
+                    return __generator(this, function (_a) {
+                        if (handle) {
+                            handle.unsubscribe();
+                        }
+                        return [2 /*return*/];
+                    });
+                }); }, 'datastore observequery cleaner');
             });
         };
         this.configure = function (config) {
@@ -1282,66 +1410,132 @@ var DataStore = /** @class */ (function () {
                     undefined;
             _this.sessionId = _this.retrieveSessionId();
         };
-        this.clear = function clear() {
-            return __awaiter(this, void 0, void 0, function () {
-                return __generator(this, function (_a) {
-                    switch (_a.label) {
-                        case 0:
-                            checkSchemaInitialized();
-                            if (!(this.storage === undefined)) return [3 /*break*/, 2];
-                            // connect to storage so that it can be cleared without fully starting DataStore
-                            this.storage = new storage_1.ExclusiveStorage(schema, namespaceResolver, getModelConstructorByModelName, modelInstanceCreator, this.storageAdapter, this.sessionId);
-                            return [4 /*yield*/, this.storage.init()];
-                        case 1:
-                            _a.sent();
-                            _a.label = 2;
-                        case 2:
-                            if (syncSubscription && !syncSubscription.closed) {
-                                syncSubscription.unsubscribe();
-                            }
-                            return [4 /*yield*/, this.storage.clear()];
-                        case 3:
-                            _a.sent();
-                            if (this.sync) {
-                                this.sync.unsubscribeConnectivity();
-                            }
-                            this.initialized = undefined; // Should re-initialize when start() is called.
-                            this.storage = undefined;
-                            this.sync = undefined;
-                            this.syncPredicates = new WeakMap();
-                            return [2 /*return*/];
-                    }
-                });
-            });
-        };
-        this.stop = function stop() {
-            return __awaiter(this, void 0, void 0, function () {
-                return __generator(this, function (_a) {
-                    switch (_a.label) {
-                        case 0:
-                            if (!(this.initialized !== undefined)) return [3 /*break*/, 2];
-                            return [4 /*yield*/, this.start()];
-                        case 1:
-                            _a.sent();
-                            _a.label = 2;
-                        case 2:
-                            if (syncSubscription && !syncSubscription.closed) {
-                                syncSubscription.unsubscribe();
-                            }
-                            if (this.sync) {
-                                this.sync.unsubscribeConnectivity();
-                            }
-                            this.initialized = undefined; // Should re-initialize when start() is called.
-                            this.sync = undefined;
-                            return [2 /*return*/];
-                    }
-                });
-            });
-        };
     }
     DataStore.prototype.getModuleName = function () {
         return 'DataStore';
     };
+    /**
+     * Builds a function to capture `BackgroundManagerNotOpenError`'s to produce friendlier,
+     * more instructive errors for customers.
+     *
+     * @param operation The name of the operation (usually a Datastore method) the customer
+     * tried to call.
+     */
+    DataStore.prototype.handleAddProcError = function (operation) {
+        var _this = this;
+        /**
+         * If the tested error is a `BackgroundManagerNotOpenError`, it will be captured
+         * and replaced with a friendlier message that instructs the App Developer.
+         *
+         * @param err An error to test.
+         */
+        var handler = function (err) {
+            if (err.message.startsWith('BackgroundManagerNotOpenError')) {
+                throw new Error([
+                    "DataStoreStateError: Tried to execute `" + operation + "` while DataStore was \"" + _this.state + "\".",
+                    "This can only be done while DataStore is \"Started\" or \"Stopped\". To remedy:",
+                    'Ensure all calls to `stop()` and `clear()` have completed first.',
+                    'If this is not possible, retry the operation until it succeeds.',
+                ].join('\n'));
+            }
+            else {
+                throw err;
+            }
+        };
+        return handler;
+    };
+    /**
+     * Clears all data from storage and removes all data, schema info, other
+     * initialization details, and then stops DataStore.
+     *
+     * That said, reinitialization is required after clearing. This can be done
+     * by explicitiliy calling `start()` or any method that implicitly starts
+     * DataStore, such as `query()`, `save()`, or `delete()`.
+     */
+    DataStore.prototype.clear = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        checkSchemaInitialized();
+                        this.state = DataStoreState.Clearing;
+                        return [4 /*yield*/, this.runningProcesses.close()];
+                    case 1:
+                        _a.sent();
+                        if (!(this.storage === undefined)) return [3 /*break*/, 3];
+                        // connect to storage so that it can be cleared without fully starting DataStore
+                        this.storage = new storage_1.ExclusiveStorage(schema, namespaceResolver, getModelConstructorByModelName, modelInstanceCreator, this.storageAdapter, this.sessionId);
+                        return [4 /*yield*/, this.storage.init()];
+                    case 2:
+                        _a.sent();
+                        _a.label = 3;
+                    case 3:
+                        if (syncSubscription && !syncSubscription.closed) {
+                            syncSubscription.unsubscribe();
+                        }
+                        if (!this.sync) return [3 /*break*/, 5];
+                        return [4 /*yield*/, this.sync.stop()];
+                    case 4:
+                        _a.sent();
+                        _a.label = 5;
+                    case 5: return [4 /*yield*/, this.storage.clear()];
+                    case 6:
+                        _a.sent();
+                        this.initialized = undefined; // Should re-initialize when start() is called.
+                        this.storage = undefined;
+                        this.sync = undefined;
+                        this.syncPredicates = new WeakMap();
+                        return [4 /*yield*/, this.runningProcesses.open()];
+                    case 7:
+                        _a.sent();
+                        this.state = DataStoreState.NotRunning;
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Stops all DataStore sync activities.
+     *
+     * TODO: "Waits for graceful termination of
+     * running queries and terminates subscriptions."
+     */
+    DataStore.prototype.stop = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.state = DataStoreState.Stopping;
+                        return [4 /*yield*/, this.runningProcesses.close()];
+                    case 1:
+                        _a.sent();
+                        if (syncSubscription && !syncSubscription.closed) {
+                            syncSubscription.unsubscribe();
+                        }
+                        if (!this.sync) return [3 /*break*/, 3];
+                        return [4 /*yield*/, this.sync.stop()];
+                    case 2:
+                        _a.sent();
+                        _a.label = 3;
+                    case 3:
+                        this.initialized = undefined; // Should re-initialize when start() is called.
+                        this.sync = undefined;
+                        return [4 /*yield*/, this.runningProcesses.open()];
+                    case 4:
+                        _a.sent();
+                        this.state = DataStoreState.NotRunning;
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Validates given pagination input from a query and creates a pagination
+     * argument for use against the storage layer.
+     *
+     * @param modelDefinition
+     * @param paginationProducer
+     */
     DataStore.prototype.processPagination = function (modelDefinition, paginationProducer) {
         var sortPredicate;
         var _a = paginationProducer || {}, limit = _a.limit, page = _a.page, sort = _a.sort;
@@ -1376,6 +1570,10 @@ var DataStore = /** @class */ (function () {
             sort: sortPredicate,
         };
     };
+    /**
+     * Examines the configured `syncExpressions` and produces a WeakMap of
+     * SchemaModel -> predicate to use during sync.
+     */
     DataStore.prototype.processSyncExpressions = function () {
         return __awaiter(this, void 0, void 0, function () {
             var syncPredicates;
@@ -1457,7 +1655,10 @@ var DataStore = /** @class */ (function () {
             return map;
         }, new WeakMap());
     };
-    // database separation for Amplify Console. Not a public API
+    /**
+     * A session ID to allow CMS to open databases against multiple apps.
+     * This session ID is only expected be set by AWS Amplify Studio.
+     */
     DataStore.prototype.retrieveSessionId = function () {
         try {
             var sessionId = sessionStorage.getItem('datastoreSessionId');