Release Firestore Bundles as a prototype patched feature. (#4168)

* Add bundles to d.ts and rearrange bundles source code for building it as a separate module (#4120)

* Add bundles to d.ts and rearrange bundles source code for building it as a separate module.

* Roll bundle with prebuilt (#4128)

Build firestore sdks with prebuilt to support bundle as a prototype patched feature.

* Add JSDoc for bundles (#4155)

Add JSDoc for bundles.

* Create changeset

* Update old-lobsters-pull.md

* A few fixes for Firestore bundle sdk builds (#4177)

* Actually creates firebase/firestore/bundle package.json

* Fix standard node/browser builds for bundles

* Make it release from remote branch.

* Add bundle to firebase complete build and fix missing proto for memory build.

* Make rollup.config.js more organized.

* Revert "Make it release from remote branch."

This reverts commit 2c91fd1.

* 2017 -> 2020

* Update comment.

* Address comments

* Update .changeset/old-lobsters-pull.md

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

* Update .changeset/old-lobsters-pull.md

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

* Add toc.

* Remove webpack change.

Co-authored-by: Sebastian Schmidt <mrschmidt@google.com>

.changeset/old-lobsters-pull.md

@@ -0,0 +1,9 @@
+---
+"firebase": minor
+"@firebase/firestore-types": minor
+"@firebase/firestore": minor
+---
+
+Release Firestore Bundles (pre-packaged Firestore data). For NPM users, this can
+be enabled via an additional import: 'firebase/firestore/bundle'. For CDN usage,
+it is enabled by default.

integration/firestore/firebase_export.ts

@@ -17,6 +17,7 @@
 
 import firebase from '@firebase/app';
 import '@firebase/firestore';
+import '@firebase/firestore/bundle';
 import { FirebaseApp } from '@firebase/app-types';
 import { Settings, FirebaseFirestore } from '@firebase/firestore-types';
 

integration/firestore/firebase_export_memory.ts

@@ -17,6 +17,7 @@
 
 import firebase from '@firebase/app';
 import '@firebase/firestore/memory';
+import '@firebase/firestore/memory-bundle';
 import { FirebaseApp } from '@firebase/app-types';
 import { Settings, FirebaseFirestore } from '@firebase/firestore-types';
 

integration/firestore/package.json

@@ -9,7 +9,7 @@
     "test": "yarn build:memory; karma start --single-run; yarn build:persistence; karma start --single-run;",
     "test:ci": "node ../../scripts/run_tests_in_ci.js -s test",
     "test:persistence": " yarn build:persistence; karma start --single-run",
-    "test:persistence:debug:": "yarn build:persistence; karma start --auto-watch --browsers Chrome",
+    "test:persistence:debug": "yarn build:persistence; karma start --auto-watch --browsers Chrome",
     "test:memory": "yarn build:memory; karma start --single-run",
     "test:memory:debug": "yarn build:memory; karma start --auto-watch --browsers Chrome"
   },

packages/firebase/firestore/bundle/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import '@firebase/firestore/bundle';

packages/firebase/firestore/bundle/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "firebase/firestore/bundle",
+  "description": "The bundle loading feature of the Cloud Firestore component.",
+  "main": "dist/index.node.cjs.js",
+  "module": "dist/index.esm.js",
+  "typings": "../empty-import.d.ts"
+}

packages/firebase/firestore/index.cdn.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import '@firebase/firestore';
+import '@firebase/firestore/bundle';

packages/firestore/rollup.config.rn.memory.js → packages/firebase/firestore/memory/bundle/index.ts

@@ -15,21 +15,9 @@
  * limitations under the License.
  */
 
-import * as path from 'path';
-import memoryPkg from './memory/package.json';
-
-const util = require('./rollup.shared');
+/**
+ * This file serves as the public entrypoint for users that import
+ * `firebase/firestore/memory`.
+ */
 
-export default {
-  input: 'index.rn.memory.ts',
-  output: {
-    file: path.resolve('./memory', memoryPkg['react-native']),
-    format: 'es',
-    sourcemap: true
-  },
-  plugins: util.es2017Plugins('rn', /* mangled= */ true),
-  external: util.resolveBrowserExterns,
-  treeshake: {
-    moduleSideEffects: false
-  }
-};
+import '@firebase/firestore/memory-bundle';

packages/firebase/firestore/memory/bundle/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "firebase/firestore/memory",
+  "description": "The bundle loading feature for the memory-only build of the Cloud Firestore JS SDK.",
+  "main": "dist/index.node.cjs.js",
+  "module": "dist/index.esm.js",
+  "typings": "../../empty-import.d.ts"
+}

packages/firebase/firestore/memory/index.cdn.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * This file serves as the public entrypoint for users that import
+ * `firebase/firestore/memory`.
+ */
+
+import '@firebase/firestore/memory';
+import '@firebase/firestore/memory-bundle';

packages/firebase/firestore/package.json

@@ -1,7 +1,7 @@
 {
   "name": "firebase/firestore",
   "description": "The Cloud Firestore component of the Firebase JS SDK.",
-  "main": "dist/index.cjs.js",
+  "main": "dist/index.node.cjs.js",
   "module": "dist/index.esm.js",
   "typings": "../empty-import.d.ts"
 }

packages/firebase/index.d.ts

@@ -8289,12 +8289,109 @@ declare namespace firebase.firestore {
      */
     terminate(): Promise<void>;
 
+    /**
+     * Loads a Firestore bundle into the local cache.
+     *
+     * @param bundleData
+     *   An object representing the bundle to be loaded. Valid objects are `ArrayBuffer`,
+     *   `ReadableStream<Uint8Array>` or `string`.
+     *
+     * @return
+     *   A `LoadBundleTask` object, which notifies callers with progress updates, and completion
+     *   or error events. It can be used as a `Promise<LoadBundleTaskProgress>`.
+     */
+    loadBundle(
+      bundleData: ArrayBuffer | ReadableStream<Uint8Array> | string
+    ): LoadBundleTask;
+
+    /**
+     * Reads a Firestore `Query` from local cache, identified by the given name.
+     *
+     * The named queries are packaged  into bundles on the server side (along
+     * with resulting documents), and loaded to local cache using `loadBundle`. Once in local
+     * cache, use this method to extract a `Query` by name.
+     */
+    namedQuery(name: string): Promise<Query<DocumentData> | null>;
+
     /**
      * @hidden
      */
     INTERNAL: { delete: () => Promise<void> };
   }
 
+  /**
+   * Represents the task of loading a Firestore bundle. It provides progress of bundle
+   * loading, as well as task completion and error events.
+   *
+   * The API is compatible with `Promise<LoadBundleTaskProgress>`.
+   */
+  export interface LoadBundleTask extends PromiseLike<LoadBundleTaskProgress> {
+    /**
+     * Registers functions to listen to bundle loading progress events.
+     * @param next
+     *   Called when there is a progress update from bundle loading. Typically `next` calls occur
+     *   each time a Firestore document is loaded from the bundle.
+     * @param error
+     *   Called when an error occurs during bundle loading. The task aborts after reporting the
+     *   error, and there should be no more updates after this.
+     * @param complete
+     *   Called when the loading task is complete.
+     */
+    onProgress(
+      next?: (progress: LoadBundleTaskProgress) => any,
+      error?: (error: Error) => any,
+      complete?: () => void
+    ): void;
+
+    /**
+     * Implements the `Promise<LoadBundleTaskProgress>.then` interface.
+     *
+     * @param onFulfilled
+     *   Called on the completion of the loading task with a final `LoadBundleTaskProgress` update.
+     *   The update will always have its `taskState` set to `"Success"`.
+     * @param onRejected
+     *   Called when an error occurs during bundle loading.
+     */
+    then<T, R>(
+      onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike<T>,
+      onRejected?: (a: Error) => R | PromiseLike<R>
+    ): Promise<T | R>;
+
+    /**
+     * Implements the `Promise<LoadBundleTaskProgress>.catch` interface.
+     *
+     * @param onRejected
+     *   Called when an error occurs during bundle loading.
+     */
+    catch<R>(
+      onRejected: (a: Error) => R | PromiseLike<R>
+    ): Promise<R | LoadBundleTaskProgress>;
+  }
+
+  /**
+   * Represents a progress update or a final state from loading bundles.
+   */
+  export interface LoadBundleTaskProgress {
+    /** How many documents have been loaded. */
+    documentsLoaded: number;
+    /** How many documents are in the bundle being loaded. */
+    totalDocuments: number;
+    /** How many bytes have been loaded. */
+    bytesLoaded: number;
+    /** How many bytes are in the bundle being loaded. */
+    totalBytes: number;
+    /** Current task state. */
+    taskState: TaskState;
+  }
+
+  /**
+   * Represents the state of bundle loading tasks.
+   *
+   * Both 'Error' and 'Success' are sinking state: task will abort or complete and there will
+   * be no more updates after they are reported.
+   */
+  export type TaskState = 'Error' | 'Running' | 'Success';
+
   /**
    * An immutable object representing a geo point in Firestore. The geo point
    * is represented as latitude/longitude pair.

packages/firebase/rollup.config.js

@@ -28,6 +28,12 @@ import pkg from './package.json';
 
 import appPkg from './app/package.json';
 
+import firestorePkg from './firestore/package.json';
+import firestoreBundlePkg from './firestore/bundle/package.json';
+
+import firestoreMemoryPkg from './firestore/memory/package.json';
+import firestoreMemoryBundlePkg from './firestore/memory/bundle/package.json';
+
 function createUmdOutputConfig(output) {
   return {
     file: output,
@@ -111,7 +117,9 @@ const appBuilds = [
 
 const componentBuilds = pkg.components
   // The "app" component is treated differently because it doesn't depend on itself.
-  .filter(component => component !== 'app')
+  // The "firestore" component is treated differently because it contains multiple
+  // sub components for different builds.
+  .filter(component => component !== 'app' && component !== 'firestore')
   .map(component => {
     const pkg = require(`./${component}/package.json`);
     return [
@@ -149,17 +157,67 @@ const componentBuilds = pkg.components
   })
   .reduce((a, b) => a.concat(b), []);
 
+const firestoreBuilds = [
+  {
+    input: `firestore/index.ts`,
+    output: [
+      {
+        file: resolve('firestore', firestorePkg.main),
+        format: 'cjs',
+        sourcemap: true
+      },
+      {
+        file: resolve('firestore', firestorePkg.module),
+        format: 'es',
+        sourcemap: true
+      }
+    ],
+    plugins,
+    external
+  },
+  {
+    input: `firestore/bundle/index.ts`,
+    output: [
+      {
+        file: resolve('firestore/bundle', firestoreBundlePkg.main),
+        format: 'cjs',
+        sourcemap: true
+      },
+      {
+        file: resolve('firestore/bundle', firestoreBundlePkg.module),
+        format: 'es',
+        sourcemap: true
+      }
+    ],
+    plugins,
+    external
+  },
+  {
+    input: `firestore/index.cdn.ts`,
+    output: createUmdOutputConfig(`firebase-firestore.js`),
+    plugins: [
+      ...plugins,
+      uglify({
+        output: {
+          ascii_only: true // escape unicode chars
+        }
+      })
+    ],
+    external: ['@firebase/app']
+  }
+];
+
 const firestoreMemoryBuilds = [
   {
     input: `firestore/memory/index.ts`,
     output: [
       {
-        file: resolve('firestore/memory', pkg.main),
+        file: resolve('firestore/memory', firestoreMemoryPkg.main),
         format: 'cjs',
         sourcemap: true
       },
       {
-        file: resolve('firestore/memory', pkg.module),
+        file: resolve('firestore/memory', firestoreMemoryPkg.module),
         format: 'es',
         sourcemap: true
       }
@@ -168,7 +226,27 @@ const firestoreMemoryBuilds = [
     external
   },
   {
-    input: `firestore/memory/index.ts`,
+    input: `firestore/memory/bundle/index.ts`,
+    output: [
+      {
+        file: resolve('firestore/memory/bundle', firestoreMemoryBundlePkg.main),
+        format: 'cjs',
+        sourcemap: true
+      },
+      {
+        file: resolve(
+          'firestore/memory/bundle',
+          firestoreMemoryBundlePkg.module
+        ),
+        format: 'es',
+        sourcemap: true
+      }
+    ],
+    plugins,
+    external
+  },
+  {
+    input: `firestore/memory/index.cdn.ts`,
     output: createUmdOutputConfig(`firebase-firestore.memory.js`),
     plugins: [...plugins, uglify()],
     external: ['@firebase/app']
@@ -276,6 +354,7 @@ const completeBuilds = [
 export default [
   ...appBuilds,
   ...componentBuilds,
+  ...firestoreBuilds,
   ...firestoreMemoryBuilds,
   ...completeBuilds
 ];

packages/firebase/src/index.cdn.ts

@@ -33,6 +33,7 @@ import { name, version } from '../package.json';
 import '../auth';
 import '../database';
 import '../firestore';
+import '../firestore/bundle';
 import '../functions';
 import '../messaging';
 import '../storage';