Cleanup

Author: schmidt-sebastian

packages/firestore/src/local/indexeddb_schema.ts

@@ -24,6 +24,33 @@ import { encode, EncodedResourcePath } from './encoded_resource_path';
 
 export const SCHEMA_VERSION = 2;
 
+/**
+ * Performs database creation and schema migrations from and up to the specified
+ * version.
+ */
+export function createOrUpgradeDb(
+    db: IDBDatabase,
+    fromVersion: number,
+    toVersion: number
+): void {
+  assert(
+      fromVersion < toVersion && fromVersion >= 0 && toVersion <= 2,
+      'Unexpected schema upgrade from v${fromVersion} to v{toVersion}.'
+  );
+
+  if (toVersion === 2) {
+    createInstanceMetadataStore(db);
+    createTargetChangeStore(db);
+  }
+
+  if (fromVersion == 0 && toVersion >= 1) {
+    createOwnerStore(db);
+    createMutationQueue(db);
+    createQueryCache(db);
+    createRemoteDocumentCache(db);
+  }
+}
+
 // TODO(mikelehen): Get rid of "as any" if/when TypeScript fixes their types.
 // https://github.com/Microsoft/TypeScript/issues/14322
 type KeyPath = any; // tslint:disable-line:no-any
@@ -73,20 +100,24 @@ export class DbMutationQueue {
   /** Keys are automatically assigned via the userId property. */
   static keyPath = 'userId';
 
+
   constructor(
     /**
-     * The normalized user ID to which this queue belongs.
+     * @param userId - The normalized user ID to which this queue belongs.
      */
     public userId: string,
+
     /**
-     * An identifier for the highest numbered batch that has been acknowledged
-     * by the server. All MutationBatches in this queue with batchIds less
-     * than or equal to this value are considered to have been acknowledged by
-     * the server.
+     * @param lastAcknowledgedBatchId - An identifier for the highest numbered
+     * batch that has been acknowledged by the server. All MutationBatches in
+     * this queue with batchIds less than or equal to this value are considered
+     * to have been acknowledged by the server.
      */
     public lastAcknowledgedBatchId: number,
+
     /**
-     * A stream token that was previously sent by the server.
+     * @param lastStreamToken - A stream token that was previously sent by the
+     * server.
      *
      * See StreamingWriteRequest in datastore.proto for more details about
      * usage.
@@ -95,10 +126,11 @@ export class DbMutationQueue {
      * only a single stream token is retained.
      */
     public lastStreamToken: string,
+
     /**
-     * An identifier for the highest numbered batch in the mutation queue. This
-     * allows for efficient insert of new batches without relying on in-memory
-     * state.
+     * @param highestPendingBatchId - An identifier for the highest numbered
+     * batch in the mutation queue. This allows for efficient insert of new
+     * batches without relying on in-memory state.
      *
      * PORTING NOTE: iOS and Android clients keep this value in-memory.
      */
@@ -125,21 +157,25 @@ export class DbMutationBatch {
 
   constructor(
     /**
-     * The normalized user ID to which this batch belongs.
+     * @userId userId - The normalized user ID to which this batch belongs.
      */
     public userId: string,
+
     /**
-     * An identifier for this batch, allocated by the mutation queue in a
-     * monotonically increasing manner.
+     * @batchId batchId - An identifier for this batch, allocated by the
+     * mutation queue in a monotonically increasing manner.
      */
     public batchId: BatchId,
+
     /**
-     * The local write time of the batch, stored as milliseconds since the
-     * epoch.
+     * @param localWriteTimeMs - The local write time of the batch, stored as
+     * milliseconds since the epoch.
      */
     public localWriteTimeMs: number,
+
     /**
-     * A list of mutations to apply. All mutations will be applied atomically.
+     * @param mutations - A list of mutations to apply. All mutations will be
+     * applied atomically.
      *
      * Mutations are serialized via JsonProtoSerializer.toMutation().
      */
@@ -251,13 +287,14 @@ export class DbRemoteDocument {
 
   constructor(
     /**
-     * Set to an instance of a DbNoDocument if it is known that no document
-     * exists.
+     * @param noDocument - Set to an instance of a DbNoDocument if it is known
+     * that no document exists.
      */
     public noDocument: DbNoDocument | null,
+
     /**
-     * Set to an instance of a Document if there's a cached version of the
-     * document.
+     * @param document - Set to an instance of a Document if there's a cached
+     * version of the document.
      */
     public document: api.Document | null
   ) {}
@@ -302,29 +339,36 @@ export class DbTarget {
 
   constructor(
     /**
-     * An auto-generated sequential numeric identifier for the query.
+     * @param targetId - An auto-generated sequential numeric identifier for the
+     * query.
      *
      * Queries are stored using their canonicalId as the key, but these
      * canonicalIds can be quite long so we additionally assign a unique
      * queryId which can be used by referenced data structures (e.g.
      * indexes) to minimize the on-disk cost.
      */
     public targetId: TargetId,
+
     /**
-     * The canonical string representing this query. This is not unique.
+     * @param canonicalId - The canonical string representing this query. This
+     * is not unique.
      */
     public canonicalId: string,
+
     /**
-     * The last readTime received from the Watch Service for this query.
+     * @param readTime - The last readTime received from the Watch Service for
+     * this query.
      *
      * This is the same value as TargetChange.read_time in the protos.
      */
     public readTime: DbTimestamp,
+
     /**
-     * An opaque, server-assigned token that allows watching a query to be
-     * resumed after disconnecting without retransmitting all the data
-     * that matches the query. The resume token essentially identifies a
-     * point in time from which the server should resume sending results.
+     * @param resumeToken - An opaque, server-assigned token that allows
+     * watching a query to be resumed after disconnecting without retransmitting
+     * all the data that matches the query. The resume token essentially
+     * identifies a point in time from which the server should resume sending
+     * results.
      *
      * This is related to the snapshotVersion in that the resumeToken
      * effectively also encodes that value, but the resumeToken is opaque
@@ -338,9 +382,11 @@ export class DbTarget {
      * This is the same value as TargetChange.resume_token in the protos.
      */
     public resumeToken: string,
+
     /**
-     * A sequence number representing the last time this query was
-     * listened to, used for garbage collection purposes.
+     * @param lastListenSequenceNumber - A sequence number representing the
+     * last time this query was listened to, used for garbage collection
+     * purposes.
      *
      * Conventionally this would be a timestamp value, but device-local
      * clocks are unreliable and they must be able to create new listens
@@ -353,8 +399,9 @@ export class DbTarget {
      * listened to.
      */
     public lastListenSequenceNumber: number,
+
     /**
-     * The query for this target.
+     * @param query - The query for this target.
      *
      * Because canonical ids are not unique we must store the actual query. We
      * use the proto to have an object we can persist without having to
@@ -390,11 +437,11 @@ export class DbTargetDocument {
 
   constructor(
     /**
-     * The targetId identifying a target.
+     * @param targetId - The targetId identifying a target.
      */
     public targetId: TargetId,
     /**
-     * The path to the document, as encoded in the key.
+     * @param path - The path to the document, as encoded in the key.
      */
     public path: EncodedResourcePath
   ) {}
@@ -421,24 +468,29 @@ export class DbTargetGlobal {
 
   constructor(
     /**
-     * The highest numbered target id across all targets.
+     * @param highestTargetId - The highest numbered target id across all
+     * targets.
      *
      * See DbTarget.targetId.
      */
     public highestTargetId: TargetId,
+
     /**
-     * The highest numbered lastListenSequenceNumber across all targets.
+     * @param highestListenSequenceNumber - The highest numbered
+     * lastListenSequenceNumber across all targets.
      *
      * See DbTarget.lastListenSequenceNumber.
      */
     public highestListenSequenceNumber: number,
+
     /**
-     * A global snapshot version representing the last consistent snapshot we
-     * received from the backend. This is monotonically increasing and any
-     * snapshots received from the backend prior to this version (e.g. for
-     * targets resumed with a resumeToken) should be suppressed (buffered)
-     * until the backend has caught up to this snapshot version again. This
-     * prevents our cache from ever going backwards in time.
+     * @param lastRemoteSnapshotVersion - A global snapshot version representing
+     * the last consistent snapshot we received from the backend. This is
+     * monotonically increasing and any snapshots received from the backend
+     * prior to this version (e.g. for targets resumed with a resumeToken)
+     * should be suppressed (buffered) until the backend has caught up to this
+     * snapshot version again. This prevents our cache from ever going backwards
+     * in time.
      */
     public lastRemoteSnapshotVersion: DbTimestamp
   ) {}
@@ -484,15 +536,17 @@ export class DbTargetChange {
 
   constructor(
     /**
-     * The targetId identifying a target.
+     * @param targetId - The targetId identifying a target.
      */
     public targetId: TargetId,
+
     /**
-     * The snapshot version, as encoded in UTC milliseconds.
+     * @param snapshotVersion - The snapshot version for this change.
      */
     public snapshotVersion: DbTimestamp,
+
     /**
-     * The keys of the changed documents in this snapshot.
+     * @param changes - The keys of the changed documents in this snapshot.
      */
     public changes: {
       added?: EncodedResourcePath[];
@@ -514,56 +568,31 @@ function createTargetChangeStore(db: IDBDatabase): void {
  * PORTING NOTE: This is used for primary-tab selection for multi-tab
  * persistence and does not need to be ported to iOS or Android.
  */
-export class DbInstance {
+export class DbInstanceMetadata {
   /** Name of the IndexedDb object store. */
-  static store = 'instanceState';
+  static store = 'instanceMetadata';
 
   /** Keys are automatically assigned via the userId and instanceKey properties. */
   static keyPath = ['userId', 'instanceKey'];
 
   constructor(
-    /** The normalized user ID to which this batch belongs.*/
+    /** userId - The normalized user ID to which this batch belongs.*/
     public userId: string,
-    /** The auto-generated instance key assigned at client startup. */
+
+    /** instanceKey - The auto-generated instance key assigned at client startup. */
     public instanceKey: string,
-    /** The last time this state was updated. */
+
+    /** updateTimeMs - The last time this state was updated. */
     public updateTimeMs: DbTimestamp
   ) {}
 }
 
-function createInstanceStore(db: IDBDatabase): void {
-  db.createObjectStore(DbInstance.store, {
-    keyPath: DbInstance.keyPath as KeyPath
+function createInstanceMetadataStore(db: IDBDatabase): void {
+  db.createObjectStore(DbInstanceMetadata.store, {
+    keyPath: DbInstanceMetadata.keyPath as KeyPath
   });
 }
 
-/**
- * Runs any migrations needed to bring the given database up to the specified
- * schema version.
- */
-export function createOrUpgradeDb(
-  db: IDBDatabase,
-  fromVersion: number,
-  toVersion: number
-): void {
-  assert(
-    fromVersion < toVersion && fromVersion >= 0 && toVersion <= 2,
-    'Unexpected schema upgrade from v${fromVersion} to v{toVersion}.'
-  );
-
-  if (toVersion === 2) {
-    createInstanceStore(db);
-    createTargetChangeStore(db);
-  }
-
-  if (fromVersion == 0 && toVersion >= 1) {
-    createOwnerStore(db);
-    createMutationQueue(db);
-    createQueryCache(db);
-    createRemoteDocumentCache(db);
-  }
-}
-
 // Exported for testing.
 export const V1_STORES = [
   DbDocumentMutation.store,
@@ -576,7 +605,7 @@ export const V1_STORES = [
   DbTarget.store
 ];
 
-const SCHEMA_V2_STORES = [DbInstance.store, DbTargetChange.store];
+const SCHEMA_V2_STORES = [DbInstanceMetadata.store, DbTargetChange.store];
 
 /**
  * The list of all IndexedDB stored used by the SDK. This is used when creating