Release Query.limitToLast(n) (#2321)

* [1/3] Query/Target split -- create Target and make remote/ and local/ work with Target. (#2254)

* [2/3] Query/Target split: make SyncEngine able to handle the mapping between Target and Query. (#2281)

* [2.8/3] Add limitToLast implementation and tests. (#2296)

* [3/3] Spec tests for limitToLast+multi-tab (#2300)

* Add spec test for single client (#2313)

* add change log for limitToLast

* Address comments

Author: wu-hui

packages/firebase/index.d.ts

@@ -8118,14 +8118,26 @@ declare namespace firebase.firestore {
     ): Query;
 
     /**
-     * Creates and returns a new Query where the results are limited to the
-     * specified number of documents.
+     * Creates and returns a new Query that only returns the first matching
+     * documents.
      *
      * @param limit The maximum number of items to return.
      * @return The created Query.
      */
     limit(limit: number): Query;
 
+    /**
+     * Creates and returns a new Query that only returns the last matching
+     * documents.
+     *
+     * You must specify at least one `orderBy` clause for `limitToLast` queries,
+     * otherwise an exception will be thrown during execution.
+     *
+     * @param limit The maximum number of items to return.
+     * @return The created Query.
+     */
+    limitToLast(limit: number): Query;
+
     /**
      * Creates and returns a new Query that starts at the provided document
      * (inclusive). The starting position is relative to the order of the query.

packages/firestore-types/index.d.ts

@@ -1089,14 +1089,26 @@ export class Query {
   ): Query;
 
   /**
-   * Creates and returns a new Query that's additionally limited to only
-   * return up to the specified number of documents.
+   * Creates and returns a new Query that only returns the first matching
+   * documents.
    *
    * @param limit The maximum number of items to return.
    * @return The created Query.
    */
   limit(limit: number): Query;
 
+  /**
+   * Creates and returns a new Query that only returns the last matching
+   * documents.
+   *
+   * Queries with `limitToLast` must have at least one `orderBy` clause on
+   * one of the document fields, or an Exception will be thrown during execution.
+   *
+   * @param limit The maximum number of items to return.
+   * @return The created Query.
+   */
+  limitToLast(limit: number): Query;
+
   /**
    * Creates and returns a new Query that starts at the provided document
    * (inclusive). The starting position is relative to the order of the query.

packages/firestore/CHANGELOG.md

@@ -5,6 +5,8 @@
   `.where()`. `in` finds documents where a specified field’s value is IN a
   specified array. `array-contains-any` finds documents where a specified field
   is an array and contains ANY element of a specified array.
+- [feature] Added `Query.limitToLast(n: number)` , which returns the last 
+  `n` documents as the result.
 
 # 1.6.3
 - [changed] Improved iOS 13 support by eliminating an additional crash in our

packages/firestore/src/api/database.ts

@@ -71,6 +71,7 @@ import {
   validateOptionalArgType,
   validateOptionalArrayElements,
   validateOptionNames,
+  validatePositiveNumber,
   validateStringEnum,
   valueDescription
 } from '../util/input_validation';
@@ -1542,14 +1543,15 @@ export class Query implements firestore.Query {
   limit(n: number): firestore.Query {
     validateExactNumberOfArgs('Query.limit', arguments, 1);
     validateArgType('Query.limit', 'number', 1, n);
-    if (n <= 0) {
-      throw new FirestoreError(
-        Code.INVALID_ARGUMENT,
-        `Invalid Query. Query limit (${n}) is invalid. Limit must be ` +
-          'positive.'
-      );
-    }
-    return new Query(this._query.withLimit(n), this.firestore);
+    validatePositiveNumber('Query.limit', 1, n);
+    return new Query(this._query.withLimitToFirst(n), this.firestore);
+  }
+
+  limitToLast(n: number): firestore.Query {
+    validateExactNumberOfArgs('Query.limitToLast', arguments, 1);
+    validateArgType('Query.limitToLast', 'number', 1, n);
+    validatePositiveNumber('Query.limitToLast', 1, n);
+    return new Query(this._query.withLimitToLast(n), this.firestore);
   }
 
   startAt(
@@ -1829,6 +1831,7 @@ export class Query implements firestore.Query {
         complete: args[currArg + 2] as CompleteFn
       };
     }
+    this.validateHasExplicitOrderByForLimitToLast(this._query);
     return this.onSnapshotInternal(options, observer);
   }
 
@@ -1864,9 +1867,19 @@ export class Query implements firestore.Query {
     };
   }
 
+  private validateHasExplicitOrderByForLimitToLast(query: InternalQuery): void {
+    if (query.hasLimitToLast() && query.explicitOrderBy.length === 0) {
+      throw new FirestoreError(
+        Code.UNIMPLEMENTED,
+        'limitToLast() queries require specifying at least one orderBy() clause'
+      );
+    }
+  }
+
   get(options?: firestore.GetOptions): Promise<firestore.QuerySnapshot> {
     validateBetweenNumberOfArgs('Query.get', arguments, 0, 1);
     validateGetOptions('Query.get', options);
+    this.validateHasExplicitOrderByForLimitToLast(this._query);
     return new Promise(
       (resolve: Resolver<firestore.QuerySnapshot>, reject: Rejecter) => {
         if (options && options.source === 'cache') {