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

package/lib-esm/datastore/datastore.d.ts

@@ -3,6 +3,15 @@ import { PredicateAll } from '../predicates';
 import { ConflictHandler, DataStoreConfig, NonModelTypeConstructor, ProducerPaginationInput, PersistentModel, PersistentModelConstructor, ProducerModelPredicate, Schema, SubscriptionMessage, DataStoreSnapshot, TypeConstructorMap, ErrorHandler, ObserveQueryOptions, PersistentModelMetaData, IdentifierFieldOrIdentifierObject } from '../types';
 export declare let syncClasses: TypeConstructorMap;
 declare const initSchema: (userSchema: Schema) => Record<string, PersistentModelConstructor<any> | NonModelTypeConstructor<unknown>>;
+/**
+ * Constructs a model and records it with its metadata in a weakset. Allows for
+ * the separate storage of core model fields and Amplify/DataStore metadata
+ * fields that the customer app does not want exposed.
+ *
+ * @param modelConstructor The model constructor.
+ * @param init Init data that would normally be passed to the constructor.
+ * @returns The initialized model.
+ */
 export declare type ModelInstanceCreator = typeof modelInstanceCreator;
 declare function modelInstanceCreator<T extends PersistentModel>(modelConstructor: PersistentModelConstructor<T>, init: Partial<T>): T;
 declare class DataStore {
@@ -26,7 +35,62 @@ declare class DataStore {
     private sessionId;
     private storageAdapter;
     private amplifyContext;
+    private connectivityMonitor?;
+    /**
+     * **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.)
+     */
+    private runningProcesses;
+    /**
+     * Indicates what state DataStore is in.
+     *
+     * Not [yet?] used for actual state management; but for messaging
+     * when errors occur, to help troubleshoot.
+     */
+    private state;
     getModuleName(): string;
+    /**
+     * 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.
+     */
+    handleAddProcError(operation: string): (err: Error) => never;
+    /**
+     * 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.
+     */
     start: () => Promise<void>;
     query: {
         <T extends PersistentModel>(modelConstructor: PersistentModelConstructor<T>, identifier: IdentifierFieldOrIdentifierObject<T, PersistentModelMetaData<T>>): Promise<T | undefined>;
@@ -50,13 +114,42 @@ declare class DataStore {
         <T extends PersistentModel>(modelConstructor: PersistentModelConstructor<T>, criteria?: ProducerModelPredicate<T> | typeof PredicateAll, paginationProducer?: ObserveQueryOptions<T>): Observable<DataStoreSnapshot<T>>;
     };
     configure: (config?: DataStoreConfig) => void;
-    clear: () => Promise<void>;
-    stop: (this: DataStore) => Promise<void>;
+    /**
+     * 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()`.
+     */
+    clear(): Promise<void>;
+    /**
+     * Stops all DataStore sync activities.
+     *
+     * TODO: "Waits for graceful termination of
+     * running queries and terminates subscriptions."
+     */
+    stop(this: InstanceType<typeof DataStore>): Promise<void>;
+    /**
+     * Validates given pagination input from a query and creates a pagination
+     * argument for use against the storage layer.
+     *
+     * @param modelDefinition
+     * @param paginationProducer
+     */
     private processPagination;
+    /**
+     * Examines the configured `syncExpressions` and produces a WeakMap of
+     * SchemaModel -> predicate to use during sync.
+     */
     private processSyncExpressions;
     private createFromCondition;
     private unwrapPromise;
     private weakMapFromEntries;
+    /**
+     * A session ID to allow CMS to open databases against multiple apps.
+     * This session ID is only expected be set by AWS Amplify Studio.
+     */
     private retrieveSessionId;
 }
 declare const instance: DataStore;