Add a custom error for schema downgrades, and a note about it (#1428)

* Add a custom error for schema downgrades, and a note about it

Author: Greg Soltis

packages/firestore/src/local/simple_db.ts

@@ -41,7 +41,14 @@ export interface SimpleDbSchemaConverter {
  * See PersistencePromise for more details.
  */
 export class SimpleDb {
-  /** Opens the specified database, creating or upgrading it if necessary. */
+  /**
+   * Opens the specified database, creating or upgrading it if necessary.
+   *
+   * Note that `version` must not be a downgrade. IndexedDB does not support downgrading the schema
+   * version. We currently do not support any way to do versioning outside of IndexedDB's versioning
+   * mechanism, as only version-upgrade transactions are allowed to do things like create
+   * objectstores.
+   */
   static openOrCreate(
     name: string,
     version: number,
@@ -76,7 +83,21 @@ export class SimpleDb {
       };
 
       request.onerror = (event: Event) => {
-        reject((event.target as IDBOpenDBRequest).error);
+        const error: DOMException = (event.target as IDBOpenDBRequest).error!;
+        if (error.name === 'VersionError') {
+          reject(
+            new FirestoreError(
+              Code.FAILED_PRECONDITION,
+              'A newer version of the Firestore SDK was previously used and so the persisted ' +
+                'data is not compatible with the version of the SDK you are now using. The SDK ' +
+                'will operate with persistence disabled. If you need persistence, please ' +
+                're-upgrade to a newer version of the SDK or else clear the persisted IndexedDB ' +
+                'data for your app to start fresh.'
+            )
+          );
+        } else {
+          reject(error);
+        }
       };
 
       request.onupgradeneeded = (event: IDBVersionChangeEvent) => {

packages/firestore/test/unit/local/indexeddb_persistence.test.ts

@@ -52,6 +52,7 @@ import { SimpleDb, SimpleDbTransaction } from '../../../src/local/simple_db';
 import { PlatformSupport } from '../../../src/platform/platform';
 import { JsonProtoSerializer } from '../../../src/remote/serializer';
 import { AsyncQueue } from '../../../src/util/async_queue';
+import { FirestoreError } from '../../../src/util/error';
 import { doc, path } from '../../util/helpers';
 import { SharedFakeWebStorage, TestPlatform } from '../../util/test_platform';
 import {
@@ -602,6 +603,30 @@ describe('IndexedDbSchema: createOrUpgradeDb', () => {
       });
     });
   });
+
+  it('downgrading throws a custom error', async () => {
+    // Upgrade to latest version
+    await withDb(SCHEMA_VERSION, async db => {
+      expect(db.version).to.equal(SCHEMA_VERSION);
+    });
+    // downgrade by one version
+    const downgradeVersion = SCHEMA_VERSION - 1;
+    const schemaConverter = new SchemaConverter(TEST_SERIALIZER);
+    let error: FirestoreError | null = null;
+    try {
+      await SimpleDb.openOrCreate(
+        INDEXEDDB_TEST_DATABASE_NAME,
+        downgradeVersion,
+        schemaConverter
+      );
+    } catch (e) {
+      error = e;
+      expect(
+        e.message.indexOf('A newer version of the Firestore SDK')
+      ).to.not.equal(-1);
+    }
+    expect(error).to.not.be.null;
+  });
 });
 
 describe('IndexedDb: canActAsPrimary', () => {