@aws-amplify/datastore 3.12.6-next.20 → 3.12.6-next.32

package/lib-esm/datastore/datastore.js

@@ -1,8 +1,8 @@
 import { __assign, __awaiter, __generator, __read, __rest, __spread, __values } from "tslib";
-import API from '@aws-amplify/api';
-import { Amplify, ConsoleLogger as Logger, Hub, JS } from '@aws-amplify/core';
+import { API } from '@aws-amplify/api';
 import { Auth } from '@aws-amplify/auth';
-import Cache from '@aws-amplify/cache';
+import { BrowserStorageCache as Cache } from '@aws-amplify/cache';
+import { Amplify, ConsoleLogger as Logger, Hub, browserOrNode, BackgroundProcessManager, } from '@aws-amplify/core';
 import { immerable, produce, setAutoFreeze, enablePatches, } from 'immer';
 import { v4 as uuid4 } from 'uuid';
 import Observable from 'zen-observable-ts';
@@ -10,13 +10,14 @@ import { defaultAuthStrategy, multiAuthStrategy } from '../authModeStrategies';
 import { isPredicatesAll, ModelPredicateCreator, ModelSortPredicateCreator, } from '../predicates';
 import { ExclusiveStorage as Storage } from '../storage/storage';
 import { ControlMessage, SyncEngine } from '../sync';
-import { GraphQLScalarType, isGraphQLScalarType, AuthModeStrategyType, isNonModelFieldType, isModelFieldType, } from '../types';
-import { DATASTORE, establishRelationAndKeys, exhaustiveCheck, isModelConstructor, monotonicUlidFactory, STORAGE, SYNC, USER, isNullOrUndefined, registerNonModelClass, sortCompareFunction, DeferredCallbackResolver, validatePredicate, mergePatches, } from '../util';
+import { GraphQLScalarType, isGraphQLScalarType, isSchemaModelWithAttributes, AuthModeStrategyType, isNonModelFieldType, isModelFieldType, isIdentifierObject, } from '../types';
+import { DATASTORE, errorMessages, establishRelationAndKeys, exhaustiveCheck, isModelConstructor, monotonicUlidFactory, STORAGE, SYNC, USER, isNullOrUndefined, registerNonModelClass, sortCompareFunction, DeferredCallbackResolver, extractPrimaryKeyFieldNames, extractPrimaryKeysAndValues, isIdManaged, isIdOptionallyManaged, validatePredicate, mergePatches, } from '../util';
+import { getIdentifierValue } from '../sync/utils';
 setAutoFreeze(true);
 enablePatches();
 var logger = new Logger('DataStore');
 var ulid = monotonicUlidFactory(Date.now());
-var isNode = JS.browserOrNode().isNode;
+var isNode = browserOrNode().isNode;
 var SETTING_SCHEMA_VERSION = 'schemaVersion';
 var schema;
 var modelNamespaceMap = new WeakMap();
@@ -116,10 +117,14 @@ var initSchema = function (userSchema) {
     });
     return userClasses;
 };
-/* Checks if the schema has been initialized by initSchema().
+/**
+ * Throws an exception if the schema has *not* been initialized
+ * by `initSchema()`.
  *
- * 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.
+ * **To be called before trying to access schema.**
+ *
+ * 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) {
@@ -143,6 +148,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);
@@ -151,15 +161,23 @@ function modelInstanceCreator(modelConstructor, init) {
 var validateModelFields = function (modelDefinition) { return function (k, v) {
     var fieldDefinition = modelDefinition.fields[k];
     if (fieldDefinition !== undefined) {
-        var type = fieldDefinition.type, isRequired_1 = fieldDefinition.isRequired, isArrayNullable = fieldDefinition.isArrayNullable, name_1 = fieldDefinition.name, isArray = fieldDefinition.isArray;
+        var type_1 = fieldDefinition.type, isRequired_1 = fieldDefinition.isRequired, isArrayNullable = fieldDefinition.isArrayNullable, name_1 = fieldDefinition.name, isArray = fieldDefinition.isArray;
         if (((!isArray && isRequired_1) || (isArray && !isArrayNullable)) &&
             (v === null || v === undefined)) {
             throw new Error("Field " + name_1 + " is required");
         }
-        if (isGraphQLScalarType(type)) {
-            var jsType_1 = GraphQLScalarType.getJSType(type);
-            var validateScalar_1 = GraphQLScalarType.getValidationFunction(type);
-            if (type === 'AWSJSON') {
+        if (isSchemaModelWithAttributes(modelDefinition) &&
+            !isIdManaged(modelDefinition)) {
+            var keys = extractPrimaryKeyFieldNames(modelDefinition);
+            if (keys.includes(k) && v === '') {
+                logger.error(errorMessages.idEmptyString, { k: k, value: v });
+                throw new Error(errorMessages.idEmptyString);
+            }
+        }
+        if (isGraphQLScalarType(type_1)) {
+            var jsType_1 = GraphQLScalarType.getJSType(type_1);
+            var validateScalar_1 = GraphQLScalarType.getValidationFunction(type_1);
+            if (type_1 === 'AWSJSON') {
                 if (typeof v === jsType_1) {
                     return;
                 }
@@ -203,7 +221,7 @@ var validateModelFields = function (modelDefinition) { return function (k, v) {
                         }
                     });
                     if (!validationStatus.every(function (s) { return s; })) {
-                        throw new Error("All elements in the " + name_1 + " array should be of type " + type + ", validation failed for one or more elements. " + v);
+                        throw new Error("All elements in the " + name_1 + " array should be of type " + type_1 + ", validation failed for one or more elements. " + v);
                     }
                 }
             }
@@ -216,7 +234,42 @@ var validateModelFields = function (modelDefinition) { return function (k, v) {
             else if (!isNullOrUndefined(v) &&
                 validateScalar_1 &&
                 !validateScalar_1(v)) {
-                throw new Error("Field " + name_1 + " should be of type " + type + ", validation failed. " + v);
+                throw new Error("Field " + name_1 + " should be of type " + type_1 + ", validation failed. " + v);
+            }
+        }
+        else if (isNonModelFieldType(type_1)) {
+            // do not check non model fields if undefined or null
+            if (!isNullOrUndefined(v)) {
+                var subNonModelDefinition_1 = schema.namespaces.user.nonModels[type_1.nonModel];
+                var modelValidator_1 = validateModelFields(subNonModelDefinition_1);
+                if (isArray) {
+                    var errorTypeText = type_1.nonModel;
+                    if (!isRequired_1) {
+                        errorTypeText = type_1.nonModel + " | null | undefined";
+                    }
+                    if (!Array.isArray(v)) {
+                        throw new Error("Field " + name_1 + " should be of type [" + errorTypeText + "], " + typeof v + " received. " + v);
+                    }
+                    v.forEach(function (item) {
+                        if ((isNullOrUndefined(item) && isRequired_1) ||
+                            (typeof item !== 'object' && typeof item !== 'undefined')) {
+                            throw new Error("All elements in the " + name_1 + " array should be of type " + type_1.nonModel + ", [" + typeof item + "] received. " + item);
+                        }
+                        if (!isNullOrUndefined(item)) {
+                            Object.keys(subNonModelDefinition_1.fields).forEach(function (subKey) {
+                                modelValidator_1(subKey, item[subKey]);
+                            });
+                        }
+                    });
+                }
+                else {
+                    if (typeof v !== 'object') {
+                        throw new Error("Field " + name_1 + " should be of type " + type_1.nonModel + ", " + typeof v + " recieved. " + v);
+                    }
+                    Object.keys(subNonModelDefinition_1.fields).forEach(function (subKey) {
+                        modelValidator_1(subKey, v[subKey]);
+                    });
+                }
             }
         }
     }
@@ -256,21 +309,29 @@ var createModelClass = function (modelDefinition) {
         function Model(init) {
             var instance = produce(this, function (draft) {
                 initializeInstance(init, modelDefinition, draft);
-                var modelInstanceMetadata = instancesMetadata.has(init)
+                // model is initialized inside a DataStore component (e.g. by Sync Engine, Storage Engine, etc.)
+                var isInternallyInitialized = instancesMetadata.has(init);
+                var modelInstanceMetadata = isInternallyInitialized
                     ? init
                     : {};
-                var _id = modelInstanceMetadata.id, _version = modelInstanceMetadata._version, _lastChangedAt = modelInstanceMetadata._lastChangedAt, _deleted = modelInstanceMetadata._deleted;
-                // instancesIds are set by modelInstanceCreator, it is accessible only internally
-                var isInternal = _id !== null && _id !== undefined;
-                var id = isInternal
-                    ? _id
-                    : modelDefinition.syncable
-                        ? uuid4()
-                        : ulid();
-                if (!isInternal) {
+                var _id = modelInstanceMetadata.id;
+                if (isIdManaged(modelDefinition)) {
+                    var isInternalModel = _id !== null && _id !== undefined;
+                    var id = isInternalModel
+                        ? _id
+                        : modelDefinition.syncable
+                            ? uuid4()
+                            : ulid();
+                    draft.id = id;
+                }
+                else if (isIdOptionallyManaged(modelDefinition)) {
+                    // only auto-populate if the id was not provided
+                    draft.id = draft.id || uuid4();
+                }
+                if (!isInternallyInitialized) {
                     checkReadOnlyPropertyOnCreate(draft, modelDefinition);
                 }
-                draft.id = id;
+                var _version = modelInstanceMetadata._version, _lastChangedAt = modelInstanceMetadata._lastChangedAt, _deleted = modelInstanceMetadata._deleted;
                 if (modelDefinition.syncable) {
                     draft._version = _version;
                     draft._lastChangedAt = _lastChangedAt;
@@ -289,7 +350,9 @@ var createModelClass = function (modelDefinition) {
             var patches;
             var model = produce(source, function (draft) {
                 fn(draft);
-                draft.id = source.id;
+                var keyNames = extractPrimaryKeyFieldNames(modelDefinition);
+                // Keys are immutable
+                keyNames.forEach(function (key) { return (draft[key] = source[key]); });
                 var modelValidator = validateModelFields(modelDefinition);
                 Object.entries(draft).forEach(function (_a) {
                     var _b = __read(_a, 2), k = _b[0], v = _b[1];
@@ -408,6 +471,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;
@@ -422,7 +497,6 @@ function checkSchemaVersion(storage, version) {
                             return __generator(this, function (_b) {
                                 switch (_b.label) {
                                     case 0: return [4 /*yield*/, s.query(Setting, ModelPredicateCreator.createFromExisting(modelDefinition, function (c) {
-                                            // @ts-ignore Argument of type '"eq"' is not assignable to parameter of type 'never'.
                                             return c.key('eq', SETTING_SCHEMA_VERSION);
                                         }), { page: 0, limit: 1 })];
                                     case 1:
@@ -491,6 +565,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;
@@ -506,156 +588,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 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(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 SyncEngine(schema, namespaceResolver, 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
-                                    ? ControlMessage.SYNC_ENGINE_SYNC_QUERIES_READY
-                                    : ControlMessage.SYNC_ENGINE_STORAGE_SUBSCRIBED;
-                                if (type === readyType) {
-                                    _this.initResolve();
-                                }
-                                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(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 SyncEngine(schema, namespaceResolver, 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
+                                                ? ControlMessage.SYNC_ENGINE_SYNC_QUERIES_READY
+                                                : ControlMessage.SYNC_ENGINE_STORAGE_SUBSCRIBED;
+                                            if (type === readyType) {
+                                                _this.initResolve();
+                                            }
+                                            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, idOrCriteria, paginationProducer) { return __awaiter(_this, void 0, void 0, function () {
-            var msg, modelDefinition, predicate, pagination, result;
+        this.query = function (modelConstructor, identifierOrCriteria, paginationProducer) { return __awaiter(_this, void 0, void 0, function () {
+            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 idOrCriteria === 'string') {
-                            if (paginationProducer !== undefined) {
-                                logger.warn('Pagination is ignored when querying by id');
-                            }
-                        }
-                        modelDefinition = getModelDefinition(modelConstructor);
-                        if (isQueryOne(idOrCriteria)) {
-                            predicate = ModelPredicateCreator.createForId(modelDefinition, idOrCriteria);
-                        }
-                        else {
-                            if (isPredicatesAll(idOrCriteria)) {
-                                // Predicates.ALL means "all records", so no predicate (undefined)
-                                predicate = undefined;
-                            }
-                            else {
-                                predicate = ModelPredicateCreator.createFromExisting(modelDefinition, idOrCriteria);
+                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 = extractPrimaryKeyFieldNames(modelDefinition);
+                                    if (isQueryOne(identifierOrCriteria)) {
+                                        if (keyFields.length > 1) {
+                                            msg = errorMessages.queryByPkWithCompositeKeyPresent;
+                                            logger.error(msg, { keyFields: keyFields });
+                                            throw new Error(msg);
+                                        }
+                                        predicate = ModelPredicateCreator.createForSingleField(modelDefinition, keyFields[0], identifierOrCriteria);
+                                    }
+                                    else {
+                                        // Object is being queried using object literal syntax
+                                        if (isIdentifierObject(identifierOrCriteria, modelDefinition)) {
+                                            predicate = ModelPredicateCreator.createForPk(modelDefinition, identifierOrCriteria);
+                                        }
+                                        else if (isPredicatesAll(identifierOrCriteria)) {
+                                            // Predicates.ALL means "all records", so no predicate (undefined)
+                                            predicate = undefined;
+                                        }
+                                        else {
+                                            predicate = ModelPredicateCreator.createFromExisting(modelDefinition, identifierOrCriteria);
+                                        }
+                                    }
+                                    pagination = this.processPagination(modelDefinition, paginationProducer);
+                                    //#endregion
+                                    logger.debug('params ready', {
+                                        modelConstructor: modelConstructor,
+                                        predicate: ModelPredicateCreator.getPredicates(predicate, false),
+                                        pagination: __assign(__assign({}, pagination), { sort: ModelSortPredicateCreator.getPredicates(pagination && pagination.sort, false) }),
+                                    });
+                                    return [4 /*yield*/, this.storage.query(modelConstructor, predicate, pagination)];
+                                case 2:
+                                    result = _a.sent();
+                                    returnOne = isQueryOne(identifierOrCriteria) ||
+                                        isIdentifierObject(identifierOrCriteria, modelDefinition);
+                                    return [2 /*return*/, returnOne ? result[0] : result];
                             }
-                        }
-                        pagination = this.processPagination(modelDefinition, paginationProducer);
-                        //#endregion
-                        logger.debug('params ready', {
-                            modelConstructor: modelConstructor,
-                            predicate: ModelPredicateCreator.getPredicates(predicate, false),
-                            pagination: __assign(__assign({}, pagination), { sort: ModelSortPredicateCreator.getPredicates(pagination && pagination.sort, false) }),
                         });
-                        return [4 /*yield*/, this.storage.query(modelConstructor, predicate, pagination)];
-                    case 2:
-                        result = _a.sent();
-                        return [2 /*return*/, isQueryOne(idOrCriteria) ? 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 = 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, ModelPredicateCreator.createForId(modelDefinition, model.id))];
+            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 = 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, 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) {
@@ -684,75 +845,95 @@ var DataStore = /** @class */ (function () {
             }
             return _this.errorHandler || defaultErrorHandler;
         };
-        this.delete = function (modelOrConstructor, idOrCriteria) { return __awaiter(_this, void 0, void 0, function () {
-            var condition, msg, modelConstructor, msg, msg, _a, deleted, model, modelConstructor, msg, modelDefinition, idPredicate, 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 (!idOrCriteria) {
-                            msg = 'Id to delete or criteria required. Do you want to delete all? Pass Predicates.ALL';
-                            logger.error(msg, { idOrCriteria: idOrCriteria });
-                            throw new Error(msg);
-                        }
-                        if (typeof idOrCriteria === 'string') {
-                            condition = ModelPredicateCreator.createForId(getModelDefinition(modelConstructor), idOrCriteria);
-                        }
-                        else {
-                            condition = ModelPredicateCreator.createFromExisting(getModelDefinition(modelConstructor), 
-                            /**
-                             * idOrCriteria is always a ProducerModelPredicate<T>, never a symbol.
-                             * The symbol is used only for typing purposes. e.g. see Predicates.ALL
-                             */
-                            idOrCriteria);
-                            if (!condition || !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);
-                        idPredicate = ModelPredicateCreator.createForId(modelDefinition, model.id);
-                        if (idOrCriteria) {
-                            if (typeof idOrCriteria !== 'function') {
-                                msg = 'Invalid criteria';
-                                logger.error(msg, { idOrCriteria: idOrCriteria });
-                                throw new Error(msg);
+        this.delete = function (modelOrConstructor, identifierOrCriteria) { return __awaiter(_this, void 0, void 0, function () {
+            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 = extractPrimaryKeyFieldNames(modelDefinition);
+                                        if (keyFields.length > 1) {
+                                            msg = errorMessages.deleteByPkWithCompositeKeyPresent;
+                                            logger.error(msg, { keyFields: keyFields });
+                                            throw new Error(msg);
+                                        }
+                                        condition = ModelPredicateCreator.createForSingleField(getModelDefinition(modelConstructor), keyFields[0], identifierOrCriteria);
+                                    }
+                                    else {
+                                        if (isIdentifierObject(identifierOrCriteria, modelDefinition)) {
+                                            condition = ModelPredicateCreator.createForPk(modelDefinition, identifierOrCriteria);
+                                        }
+                                        else {
+                                            condition = 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 ||
+                                            !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 = 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 = idOrCriteria(idPredicate);
-                        }
-                        else {
-                            condition = idPredicate;
-                        }
-                        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, idOrCriteria) {
+        this.observe = function (modelOrConstructor, identifierOrCriteria) {
             var predicate;
             var modelConstructor = modelOrConstructor && isValidModelConstructor(modelOrConstructor)
                 ? modelOrConstructor
@@ -761,10 +942,10 @@ var DataStore = /** @class */ (function () {
                 var model = modelOrConstructor;
                 var modelConstructor_1 = model && Object.getPrototypeOf(model).constructor;
                 if (isValidModelConstructor(modelConstructor_1)) {
-                    if (idOrCriteria) {
+                    if (identifierOrCriteria) {
                         logger.warn('idOrCriteria is ignored when using a model instance', {
                             model: model,
-                            idOrCriteria: idOrCriteria,
+                            identifierOrCriteria: identifierOrCriteria,
                         });
                     }
                     return _this.observe(modelConstructor_1, model.id);
@@ -775,9 +956,17 @@ var DataStore = /** @class */ (function () {
                     throw new Error(msg);
                 }
             }
-            if (idOrCriteria !== undefined && modelConstructor === undefined) {
+            // observe should not accept object literal syntax
+            if (identifierOrCriteria &&
+                modelConstructor &&
+                isIdentifierObject(identifierOrCriteria, getModelDefinition(modelConstructor))) {
+                var msg = errorMessages.observeWithObjectLiteral;
+                logger.error(msg, { objectLiteral: identifierOrCriteria });
+                throw new Error(msg);
+            }
+            if (identifierOrCriteria !== undefined && modelConstructor === undefined) {
                 var msg = 'Cannot provide criteria without a modelConstructor';
-                logger.error(msg, idOrCriteria);
+                logger.error(msg, identifierOrCriteria);
                 throw new Error(msg);
             }
             if (modelConstructor && !isValidModelConstructor(modelConstructor)) {
@@ -785,17 +974,25 @@ var DataStore = /** @class */ (function () {
                 logger.error(msg, { modelConstructor: modelConstructor });
                 throw new Error(msg);
             }
-            if (typeof idOrCriteria === 'string') {
-                predicate = ModelPredicateCreator.createForId(getModelDefinition(modelConstructor), idOrCriteria);
+            if (typeof identifierOrCriteria === 'string') {
+                var modelDefinition = getModelDefinition(modelConstructor);
+                var _a = __read(extractPrimaryKeyFieldNames(modelDefinition), 1), keyField = _a[0];
+                predicate = ModelPredicateCreator.createForSingleField(getModelDefinition(modelConstructor), keyField, identifierOrCriteria);
             }
             else {
-                predicate =
-                    modelConstructor &&
-                        ModelPredicateCreator.createFromExisting(getModelDefinition(modelConstructor), idOrCriteria);
+                if (isPredicatesAll(identifierOrCriteria)) {
+                    predicate = undefined;
+                }
+                else {
+                    predicate =
+                        modelConstructor &&
+                            ModelPredicateCreator.createFromExisting(getModelDefinition(modelConstructor), identifierOrCriteria);
+                }
             }
             return new Observable(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) {
@@ -811,36 +1008,52 @@ var DataStore = /** @class */ (function () {
                                     return namespaceResolver(model) === USER;
                                 })
                                     .subscribe({
-                                    next: function (item) { return __awaiter(_this, void 0, void 0, function () {
-                                        var message, freshElement;
-                                        return __generator(this, function (_a) {
-                                            switch (_a.label) {
-                                                case 0:
-                                                    message = item;
-                                                    if (!(item.opType !== 'DELETE')) return [3 /*break*/, 2];
-                                                    return [4 /*yield*/, this.query(item.model, item.element.id)];
-                                                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 = extractPrimaryKeyFieldNames(modelDefinition);
+                                                            primaryKeysAndValues = 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) {
@@ -874,8 +1087,9 @@ var DataStore = /** @class */ (function () {
                 var sort = (options || {}).sort;
                 var sortOptions = sort ? { sort: sort } : undefined;
                 var modelDefinition = getModelDefinition(model);
+                var keyFields = extractPrimaryKeyFieldNames(modelDefinition);
                 if (isQueryOne(criteria)) {
-                    predicate = ModelPredicateCreator.createForId(modelDefinition, criteria);
+                    predicate = ModelPredicateCreator.createForSingleField(modelDefinition, keyFields[0], criteria);
                 }
                 else {
                     if (isPredicatesAll(criteria)) {
@@ -888,7 +1102,8 @@ var DataStore = /** @class */ (function () {
                 }
                 var _a = 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) {
@@ -899,7 +1114,9 @@ var DataStore = /** @class */ (function () {
                             case 1:
                                 // first, query and return any locally-available records
                                 (_a.sent()).forEach(function (item) {
-                                    return items.set(item.id, item);
+                                    var itemModelDefinition = getModelDefinition(model);
+                                    var idOrPk = getIdentifierValue(itemModelDefinition, item);
+                                    items.set(idOrPk, item);
                                 });
                                 // Observe the model and send a stream of updates (debounced).
                                 // We need to post-filter results instead of passing criteria through
@@ -908,15 +1125,17 @@ var DataStore = /** @class */ (function () {
                                 handle = this.observe(model).subscribe(function (_a) {
                                     var element = _a.element, model = _a.model, opType = _a.opType;
                                     var _b, _c;
+                                    var itemModelDefinition = getModelDefinition(model);
+                                    var idOrPk = getIdentifierValue(itemModelDefinition, element);
                                     if (hasPredicate &&
                                         !validatePredicate(element, predicateGroupType, predicates)) {
                                         if (opType === 'UPDATE' &&
-                                            (items.has(element.id) || itemsChanged.has(element.id))) {
+                                            (items.has(idOrPk) || itemsChanged.has(idOrPk))) {
                                             // tracking as a "deleted item" will include the item in
                                             // page limit calculations and ensure it is removed from the
                                             // final items collection, regardless of which collection(s)
                                             // it is currently in. (I mean, it could be in both, right!?)
-                                            deletedItemIds.push(element.id);
+                                            deletedItemIds.push(idOrPk);
                                         }
                                         else {
                                             // ignore updates for irrelevant/filtered items.
@@ -928,13 +1147,14 @@ var DataStore = /** @class */ (function () {
                                     // in the `mergePage` method within src/sync/merger.ts. The final state of a model instance
                                     // depends on the LATEST record (for a given id).
                                     if (opType === 'DELETE') {
-                                        deletedItemIds.push(element.id);
+                                        deletedItemIds.push(idOrPk);
                                     }
                                     else {
-                                        itemsChanged.set(element.id, element);
+                                        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();
                                     }
@@ -951,7 +1171,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}`.
@@ -966,9 +1190,13 @@ var DataStore = /** @class */ (function () {
                         sortItems(itemsArray);
                     }
                     items.clear();
-                    itemsArray.forEach(function (item) { return items.set(item.id, item); });
+                    itemsArray.forEach(function (item) {
+                        var itemModelDefinition = getModelDefinition(model);
+                        var idOrPk = getIdentifierValue(itemModelDefinition, item);
+                        items.set(idOrPk, item);
+                    });
                     // remove deleted items from the final result set
-                    deletedItemIds.forEach(function (id) { return items.delete(id); });
+                    deletedItemIds.forEach(function (idOrPk) { return items.delete(idOrPk); });
                     return {
                         items: Array.from(items.values()),
                         isSynced: isSynced,
@@ -983,7 +1211,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();
@@ -1019,15 +1248,18 @@ var DataStore = /** @class */ (function () {
                     if (event === 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();
-                        Hub.remove('api', hubCallback);
+                        Hub.remove('datastore', hubCallback);
                     }
                 };
                 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) {
@@ -1086,66 +1318,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(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(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;
@@ -1180,6 +1478,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;
@@ -1261,7 +1563,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');
@@ -1272,9 +1577,8 @@ var DataStore = /** @class */ (function () {
                 return sessionId + "-" + appSyncId;
             }
         }
-        catch (_b) {
-            return undefined;
-        }
+        catch (_b) { }
+        return undefined;
     };
     return DataStore;
 }());