@firebase/firestore 3.7.3 → 3.8.0-canary.20e5ef7fb

package/dist/firestore/test/unit/core/filter.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */
+export {};

package/dist/firestore/test/unit/specs/spec_test_runner.d.ts

@@ -218,7 +218,7 @@ export interface SpecWatchEntity {
 }
 export interface SpecClientState {
     /** The visibility state of the browser tab running the client. */
-    visibility?: VisibilityState;
+    visibility?: DocumentVisibilityState;
     /** Whether this tab should try to forcefully become primary. */
     primary?: true;
 }
@@ -262,6 +262,7 @@ export interface SpecQuery {
 export interface SpecDocument {
     key: string;
     version: TestSnapshotVersion;
+    createTime: TestSnapshotVersion;
     value: JsonObject<unknown> | null;
     options?: DocumentOptions;
 }

package/dist/firestore/test/unit/util/logic_utils.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */
+export {};

package/dist/firestore/test/util/helpers.d.ts

@@ -15,11 +15,13 @@
  * limitations under the License.
  */
 import { Bytes, DocumentReference } from '../../src';
+import { Bound } from '../../src/core/bound';
 import { BundledDocuments } from '../../src/core/bundle';
 import { DatabaseId } from '../../src/core/database_info';
+import { FieldFilter, CompositeFilter, Filter } from '../../src/core/filter';
+import { OrderBy } from '../../src/core/order_by';
 import { Query } from '../../src/core/query';
 import { SnapshotVersion } from '../../src/core/snapshot_version';
-import { Bound, FieldFilter, Filter, OrderBy } from '../../src/core/target';
 import { TargetId } from '../../src/core/types';
 import { LimboDocumentChange, View, ViewChange } from '../../src/core/view';
 import { UserDataReader } from '../../src/lite-api/user_data_reader';
@@ -47,7 +49,7 @@ export declare type TestSnapshotVersion = number;
 export declare function testUserDataReader(useProto3Json?: boolean): UserDataReader;
 export declare function version(v: TestSnapshotVersion): SnapshotVersion;
 export declare function ref(key: string, offset?: number): DocumentReference;
-export declare function doc(keyStr: string, ver: TestSnapshotVersion, jsonOrObjectValue: JsonObject<unknown> | ObjectValue): MutableDocument;
+export declare function doc(keyStr: string, ver: TestSnapshotVersion, jsonOrObjectValue: JsonObject<unknown> | ObjectValue, createTime?: TestSnapshotVersion): MutableDocument;
 export declare function deletedDoc(keyStr: string, ver: TestSnapshotVersion): MutableDocument;
 export declare function unknownDoc(keyStr: string, ver: TestSnapshotVersion): MutableDocument;
 export declare function removedDoc(keyStr: string): MutableDocument;
@@ -68,6 +70,8 @@ export declare function fieldIndex(collectionGroup: string, options?: {
 export declare function mask(...paths: string[]): FieldMask;
 export declare function blob(...bytes: number[]): Bytes;
 export declare function filter(path: string, op: string, value: unknown): FieldFilter;
+export declare function andFilter(...filters: Filter[]): CompositeFilter;
+export declare function orFilter(...filters: Filter[]): CompositeFilter;
 export declare function setMutation(keyStr: string, json: JsonObject<unknown>): SetMutation;
 export declare function patchMutation(keyStr: string, json: JsonObject<unknown>, precondition?: Precondition): PatchMutation;
 export declare function mergeMutation(keyStr: string, json: JsonObject<unknown>, updateMask: FieldPath[]): PatchMutation;

package/dist/firestore/test/util/test_platform.d.ts

@@ -36,10 +36,10 @@ export declare function testWindow(sharedWebStorage?: SharedFakeWebStorage): Fak
 export declare class FakeDocument implements DocumentLike {
     private _visibilityState;
     private visibilityListener;
-    get visibilityState(): VisibilityState;
+    get visibilityState(): DocumentVisibilityState;
     addEventListener(type: string, listener: EventListener): void;
     removeEventListener(type: string, listener: EventListener): void;
-    raiseVisibilityEvent(visibility: VisibilityState): void;
+    raiseVisibilityEvent(visibility: DocumentVisibilityState): void;
 }
 export declare function testDocument(): FakeDocument;
 /**

package/dist/index.d.ts

@@ -578,45 +578,45 @@ export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore)
  */
 export declare function enableNetwork(firestore: Firestore): Promise<void>;
 /**
- * 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
@@ -974,7 +974,8 @@ export declare function getDocFromServer<T>(reference: DocumentReference<T>): Pr
 export declare function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
 /**
  * Executes the query and returns the results as a `QuerySnapshot` from cache.
- * Returns an error if the document is not currently cached.
+ * Returns an empty result set if no documents matching the query are currently
+ * cached.
  *
  * @returns A `Promise` that will be resolved with the results of the query.
  */
@@ -1087,22 +1088,24 @@ export declare interface IndexField {
 export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore;
 /* Excluded from this release type: _isBase64Available */
 /**
- * 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;
 /**
  * Loads a Firestore bundle into the local cache.
  *
@@ -1377,15 +1380,18 @@ export declare function onSnapshotsInSync(firestore: Firestore, observer: {
  */
 export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe;
 /**
- * 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).
@@ -1453,26 +1459,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. */
@@ -1504,6 +1513,17 @@ export declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSna
      */
     data(options?: SnapshotOptions): 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.
@@ -1514,6 +1534,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
@@ -1558,6 +1624,17 @@ export declare class QuerySnapshot<T = DocumentData> {
      */
     docChanges(options?: SnapshotListenOptions): Array<DocumentChange<T>>;
 }
+/**
+ * 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.
  *
@@ -1772,45 +1849,45 @@ export declare interface SnapshotOptions {
     readonly serverTimestamps?: 'estimate' | 'previous' | 'none';
 }
 /**
- * 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;
 /**
  * Represents the state of bundle loading tasks.
  *
@@ -2133,17 +2210,17 @@ export declare function updateDoc(reference: DocumentReference<unknown>, field:
  */
 export declare function waitForPendingWrites(firestore: Firestore): 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',