@firebase/firestore 3.7.3 → 3.8.0

package/dist/lite/index.d.ts

@@ -453,45 +453,45 @@ export declare class DocumentSnapshot<T = DocumentData> {
 }
 export { EmulatorMockTokenOptions };
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to end at the
- * provided document (inclusive). The end position is relative to the order of
- * the query. The document must contain all of the fields provided in the
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at
+ * the provided document (inclusive). The end position is relative to the order
+ * of the query. The document must contain all of the fields provided in the
  * orderBy of the query.
  *
  * @param snapshot - The snapshot of the document to end at.
- * @returns A {@link QueryConstraint} to pass to `query()`
+ * @returns A {@link QueryEndAtConstraint} to pass to `query()`
  */
-export declare function endAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export declare function endAt(snapshot: DocumentSnapshot<unknown>): QueryEndAtConstraint;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to end at the
- * provided fields relative to the order of the query. The order of the field
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at
+ * the provided fields relative to the order of the query. The order of the field
  * values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to end this query at, in order
  * of the query's order by.
- * @returns A {@link QueryConstraint} to pass to `query()`
+ * @returns A {@link QueryEndAtConstraint} to pass to `query()`
  */
-export declare function endAt(...fieldValues: unknown[]): QueryConstraint;
+export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to end before the
- * provided document (exclusive). The end position is relative to the order of
- * the query. The document must contain all of the fields provided in the
- * orderBy of the query.
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end
+ * before the provided document (exclusive). The end position is relative to the
+ * order of the query. The document must contain all of the fields provided in
+ * the orderBy of the query.
  *
  * @param snapshot - The snapshot of the document to end before.
- * @returns A {@link QueryConstraint} to pass to `query()`
+ * @returns A {@link QueryEndAtConstraint} to pass to `query()`
  */
-export declare function endBefore(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export declare function endBefore(snapshot: DocumentSnapshot<unknown>): QueryEndAtConstraint;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to end before the
- * provided fields relative to the order of the query. The order of the field
- * values must match the order of the order by clauses of the query.
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end
+ * before the provided fields relative to the order of the query. The order of
+ * the field values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to end this query before, in order
  * of the query's order by.
- * @returns A {@link QueryConstraint} to pass to `query()`
+ * @returns A {@link QueryEndAtConstraint} to pass to `query()`
  */
-export declare function endBefore(...fieldValues: unknown[]): QueryConstraint;
+export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;
 /**
  * A `FieldPath` refers to a field in a document. The path may consist of a
  * single field name (referring to a top-level field in the document), or a
@@ -820,22 +820,24 @@ export declare function increment(n: number): FieldValue;
 export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore;
 /* Excluded declaration from this release type: initializeFirestore */
 /**
- * Creates a {@link QueryConstraint} that only returns the first matching documents.
+ * Creates a {@link QueryLimitConstraint} that only returns the first matching
+ * documents.
  *
  * @param limit - The maximum number of items to return.
- * @returns The created {@link Query}.
+ * @returns The created {@link QueryLimitConstraint}.
  */
-export declare function limit(limit: number): QueryConstraint;
+export declare function limit(limit: number): QueryLimitConstraint;
 /**
- * Creates a {@link QueryConstraint} that only returns the last matching documents.
+ * Creates a {@link QueryLimitConstraint} 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.
- * @returns The created {@link Query}.
+ * @returns The created {@link QueryLimitConstraint}.
  */
-export declare function limitToLast(limit: number): QueryConstraint;
+export declare function limitToLast(limit: number): QueryLimitConstraint;
 export { LogLevel };
 /**
  * For each field (e.g. 'bar'), find all nested keys (e.g. {'bar.baz': T1,
@@ -846,15 +848,18 @@ export declare type NestedUpdateFields<T extends Record<string, unknown>> = Unio
     [K in keyof T & string]: ChildUpdateFields<K, T[K]>;
 }[keyof T & string]>;
 /**
- * Creates a {@link QueryConstraint} that sorts the query result by the
+ * Creates a {@link QueryOrderByConstraint} that sorts the query result by the
  * specified field, optionally in descending order instead of ascending.
  *
+ * Note: Documents that do not contain the specified field will not be present
+ * in the query result.
+ *
  * @param fieldPath - The field to sort by.
  * @param directionStr - Optional direction to sort by ('asc' or 'desc'). If
  * not specified, order will be ascending.
- * @returns The created {@link Query}.
+ * @returns The created {@link QueryOrderByConstraint}.
  */
-export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryConstraint;
+export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint;
 /**
  * The direction of a {@link orderBy} clause is specified as 'desc' or 'asc'
  * (descending or ascending).
@@ -909,26 +914,29 @@ export declare class Query<T = DocumentData> {
      */
     withConverter<U>(converter: FirestoreDataConverter<U>): Query<U>;
 }
+/* Excluded declaration from this release type: query */
 /**
- * Creates a new immutable instance of {@link Query} that is extended to also include
- * additional query constraints.
+ * Creates a new immutable instance of {@link Query} that is extended to also
+ * include additional query constraints.
  *
- * @param query - The {@link Query} instance to use as a base for the new constraints.
+ * @param query - The {@link Query} instance to use as a base for the new
+ * constraints.
  * @param queryConstraints - The list of {@link QueryConstraint}s to apply.
  * @throws if any of the provided query constraints cannot be combined with the
  * existing or new constraints.
  */
 export declare function query<T>(query: Query<T>, ...queryConstraints: QueryConstraint[]): Query<T>;
+/* Excluded from this release type: QueryCompositeFilterConstraint */
 /**
  * A `QueryConstraint` is used to narrow the set of documents returned by a
  * Firestore query. `QueryConstraint`s are created by invoking {@link where},
- * {@link orderBy}, {@link (startAt:1)}, {@link (startAfter:1)}, {@link
- * endBefore:1}, {@link (endAt:1)}, {@link limit} or {@link limitToLast} and
+ * {@link orderBy}, {@link startAt}, {@link startAfter}, {@link
+ * endBefore}, {@link endAt}, {@link limit}, {@link limitToLast} and
  * can then be passed to {@link query} to create a new query instance that
  * also contains this `QueryConstraint`.
  */
 export declare abstract class QueryConstraint {
-    /** The type of this query constraints */
+    /** The type of this query constraint */
     abstract readonly type: QueryConstraintType;
 }
 /** Describes the different query constraints available in this SDK. */
@@ -953,6 +961,17 @@ export declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSna
      */
     data(): T;
 }
+/**
+ * A `QueryEndAtConstraint` is used to exclude documents from the end of a
+ * result set returned by a Firestore query.
+ * `QueryEndAtConstraint`s are created by invoking {@link (endAt:1)} or
+ * {@link (endBefore:1)} and can then be passed to {@link query} to create a new
+ * query instance that also contains this `QueryEndAtConstraint`.
+ */
+export declare class QueryEndAtConstraint extends QueryConstraint {
+    /** The type of this query constraint */
+    readonly type: 'endBefore' | 'endAt';
+}
 /**
  * Returns true if the provided queries point to the same collection and apply
  * the same constraints.
@@ -963,6 +982,52 @@ export declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSna
  * Firestore database.
  */
 export declare function queryEqual<T>(left: Query<T>, right: Query<T>): boolean;
+/**
+ * A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by
+ * a Firestore query by filtering on one or more document fields.
+ * `QueryFieldFilterConstraint`s are created by invoking {@link where} and can then
+ * be passed to {@link query} to create a new query instance that also contains
+ * this `QueryFieldFilterConstraint`.
+ */
+export declare class QueryFieldFilterConstraint extends QueryConstraint {
+    /** The type of this query constraint */
+    readonly type = "where";
+}
+/* Excluded from this release type: QueryFilterConstraint */
+/**
+ * A `QueryLimitConstraint` is used to limit the number of documents returned by
+ * a Firestore query.
+ * `QueryLimitConstraint`s are created by invoking {@link limit} or
+ * {@link limitToLast} and can then be passed to {@link query} to create a new
+ * query instance that also contains this `QueryLimitConstraint`.
+ */
+export declare class QueryLimitConstraint extends QueryConstraint {
+    /** The type of this query constraint */
+    readonly type: 'limit' | 'limitToLast';
+}
+/**
+ * `QueryNonFilterConstraint` is a helper union type that represents
+ * QueryConstraints which are used to narrow or order the set of documents,
+ * but that do not explicitly filter on a document field.
+ * `QueryNonFilterConstraint`s are created by invoking {@link orderBy},
+ * {@link startAt}, {@link startAfter}, {@link endBefore}, {@link endAt},
+ * {@link limit} or {@link limitToLast} and can then be passed to {@link query}
+ * to create a new query instance that also contains the `QueryConstraint`.
+ */
+export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint;
+/**
+ * A `QueryOrderByConstraint` is used to sort the set of documents returned by a
+ * Firestore query. `QueryOrderByConstraint`s are created by invoking
+ * {@link orderBy} and can then be passed to {@link query} to create a new query
+ * instance that also contains this `QueryOrderByConstraint`.
+ *
+ * Note: Documents that do not contain the orderBy field will not be present in
+ * the query result.
+ */
+export declare class QueryOrderByConstraint extends QueryConstraint {
+    /** The type of this query constraint */
+    readonly type = "orderBy";
+}
 /**
  * A `QuerySnapshot` contains zero or more `DocumentSnapshot` objects
  * representing the results of a query. The documents can be accessed as an
@@ -992,6 +1057,17 @@ export declare class QuerySnapshot<T = DocumentData> {
      */
     forEach(callback: (result: QueryDocumentSnapshot<T>) => void, thisArg?: unknown): void;
 }
+/**
+ * A `QueryStartAtConstraint` is used to exclude documents from the start of a
+ * result set returned by a Firestore query.
+ * `QueryStartAtConstraint`s are created by invoking {@link (startAt:1)} or
+ * {@link (startAfter:1)} and can then be passed to {@link query} to create a
+ * new query instance that also contains this `QueryStartAtConstraint`.
+ */
+export declare class QueryStartAtConstraint extends QueryConstraint {
+    /** The type of this query constraint */
+    readonly type: 'startAt' | 'startAfter';
+}
 /**
  * Returns true if the provided references are equal.
  *
@@ -1121,45 +1197,45 @@ export declare interface Settings {
  */
 export declare function snapshotEqual<T>(left: DocumentSnapshot<T> | QuerySnapshot<T>, right: DocumentSnapshot<T> | QuerySnapshot<T>): boolean;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to start after the
- * provided document (exclusive). The starting position is relative to the order
- * of the query. The document must contain all of the fields provided in the
- * orderBy of the query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start after the provided document (exclusive). The starting position is
+ * relative to the order of the query. The document must contain all of the
+ * fields provided in the orderBy of the query.
  *
  * @param snapshot - The snapshot of the document to start after.
- * @returns A {@link QueryConstraint} to pass to `query()`
+ * @returns A {@link QueryStartAtConstraint} to pass to `query()`
  */
-export declare function startAfter(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export declare function startAfter(snapshot: DocumentSnapshot<unknown>): QueryStartAtConstraint;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to start after the
- * provided fields relative to the order of the query. The order of the field
- * values must match the order of the order by clauses of the query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start after the provided fields relative to the order of the query. The order
+ * of the field values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to start this query after, in order
  * of the query's order by.
- * @returns A {@link QueryConstraint} to pass to `query()`
+ * @returns A {@link QueryStartAtConstraint} to pass to `query()`
  */
-export declare function startAfter(...fieldValues: unknown[]): QueryConstraint;
+export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to start at the
- * provided document (inclusive). The starting position is relative to the order
- * of the query. The document must contain all of the fields provided in the
- * `orderBy` of this query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start at the provided document (inclusive). The starting position is relative
+ * to the order of the query. The document must contain all of the fields
+ * provided in the `orderBy` of this query.
  *
  * @param snapshot - The snapshot of the document to start at.
- * @returns A {@link QueryConstraint} to pass to `query()`.
+ * @returns A {@link QueryStartAtConstraint} to pass to `query()`.
  */
-export declare function startAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;
+export declare function startAt(snapshot: DocumentSnapshot<unknown>): QueryStartAtConstraint;
 /**
- * Creates a {@link QueryConstraint} that modifies the result set to start at the
- * provided fields relative to the order of the query. The order of the field
- * values must match the order of the order by clauses of the query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start at the provided fields relative to the order of the query. The order of
+ * the field values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to start this query at, in order
  * of the query's order by.
- * @returns A {@link QueryConstraint} to pass to `query()`.
+ * @returns A {@link QueryStartAtConstraint} to pass to `query()`.
  */
-export declare function startAt(...fieldValues: unknown[]): QueryConstraint;
+export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;
 /**
  * Terminates the provided `Firestore` instance.
  *
@@ -1461,17 +1537,17 @@ export declare function updateDoc<T>(reference: DocumentReference<T>, data: Upda
  */
 export declare function updateDoc(reference: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;
 /**
- * Creates a {@link QueryConstraint} that enforces that documents must contain the
- * specified field and that the value should satisfy the relation constraint
- * provided.
+ * Creates a {@link QueryFieldFilterConstraint} that enforces that documents
+ * must contain the specified field and that the value should satisfy the
+ * relation constraint provided.
  *
  * @param fieldPath - The path to compare
  * @param opStr - The operation string (e.g "&lt;", "&lt;=", "==", "&lt;",
  *   "&lt;=", "!=").
  * @param value - The value for comparison
- * @returns The created {@link Query}.
+ * @returns The created {@link QueryFieldFilterConstraint}.
  */
-export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryConstraint;
+export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint;
 /**
  * Filter conditions in a {@link where} clause are specified using the
  * strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in',