@firebase/firestore 3.8.4 → 3.9.0-20230314181055

package/dist/lite/index.d.ts

@@ -99,6 +99,18 @@ export declare interface AggregateSpec {
 export declare type AggregateSpecData<T extends AggregateSpec> = {
     [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
 };
+/* Excluded from this release type: AggregateType */
+/**
+ * Creates a new {@link QueryCompositeFilterConstraint} that is a conjunction of
+ * the given filter constraints. A conjunction filter includes a document if it
+ * satisfies all of the given filters.
+ *
+ * @param queryConstraints - Optional. The list of
+ * {@link QueryFilterConstraint}s to perform a conjunction for. These must be
+ * created with calls to {@link where}, {@link or}, or {@link and}.
+ * @returns The newly created {@link QueryCompositeFilterConstraint}.
+ */
+export declare function and(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
 /**
  * Returns a special value that can be used with {@link (setDoc:1)} or {@link
  * updateDoc:1} that tells the server to remove the given elements from any
@@ -233,7 +245,7 @@ export declare function collection(reference: DocumentReference, path: string, .
 export declare function collectionGroup(firestore: Firestore, collectionId: string): Query<DocumentData>;
 /**
  * A `CollectionReference` object can be used for adding documents, getting
- * document references, and querying for documents (using {@link query}).
+ * document references, and querying for documents (using {@link (query:1)}).
  */
 export declare class CollectionReference<T = DocumentData> extends Query<T> {
     /** The type of this Firestore reference. */
@@ -849,6 +861,17 @@ export { LogLevel };
 export declare type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection<{
     [K in keyof T & string]: ChildUpdateFields<K, T[K]>;
 }[keyof T & string]>;
+/**
+ * Creates a new {@link QueryCompositeFilterConstraint} that is a disjunction of
+ * the given filter constraints. A disjunction filter includes a document if it
+ * satisfies any of the given filters.
+ *
+ * @param queryConstraints - Optional. The list of
+ * {@link QueryFilterConstraint}s to perform a disjunction for. These must be
+ * created with calls to {@link where}, {@link or}, or {@link and}.
+ * @returns The newly created {@link QueryCompositeFilterConstraint}.
+ */
+export declare function or(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;
 /**
  * Creates a {@link QueryOrderByConstraint} that sorts the query result by the
  * specified field, optionally in descending order instead of ascending.
@@ -916,7 +939,21 @@ 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.
+ *
+ * @param query - The {@link Query} instance to use as a base for the new
+ * constraints.
+ * @param compositeFilter - The {@link QueryCompositeFilterConstraint} to
+ * apply. Create {@link QueryCompositeFilterConstraint} using {@link and} or
+ * {@link or}.
+ * @param queryConstraints - Additional {@link QueryNonFilterConstraint}s to
+ * apply (e.g. {@link orderBy}, {@link limit}).
+ * @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>, compositeFilter: QueryCompositeFilterConstraint, ...queryConstraints: QueryNonFilterConstraint[]): Query<T>;
 /**
  * Creates a new immutable instance of {@link Query} that is extended to also
  * include additional query constraints.
@@ -928,13 +965,24 @@ export declare class Query<T = DocumentData> {
  * existing or new constraints.
  */
 export declare function query<T>(query: Query<T>, ...queryConstraints: QueryConstraint[]): Query<T>;
-/* Excluded from this release type: QueryCompositeFilterConstraint */
+/**
+ * A `QueryCompositeFilterConstraint` is used to narrow the set of documents
+ * returned by a Firestore query by performing the logical OR or AND of multiple
+ * {@link QueryFieldFilterConstraint}s or {@link QueryCompositeFilterConstraint}s.
+ * `QueryCompositeFilterConstraint`s are created by invoking {@link or} or
+ * {@link and} and can then be passed to {@link (query:1)} to create a new query
+ * instance that also contains the `QueryCompositeFilterConstraint`.
+ */
+export declare class QueryCompositeFilterConstraint {
+    /** The type of this query constraint */
+    readonly type: 'or' | 'and';
+}
 /**
  * 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}, {@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
+ * {@link orderBy}, {@link (startAt:1)}, {@link (startAfter:1)}, {@link
+ * (endBefore:1)}, {@link (endAt:1)}, {@link limit}, {@link limitToLast} and
+ * can then be passed to {@link (query:1)} to create a new query instance that
  * also contains this `QueryConstraint`.
  */
 export declare abstract class QueryConstraint {
@@ -967,7 +1015,7 @@ export declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSna
  * 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
+ * {@link (endBefore:1)} and can then be passed to {@link (query:1)} to create a new
  * query instance that also contains this `QueryEndAtConstraint`.
  */
 export declare class QueryEndAtConstraint extends QueryConstraint {
@@ -988,19 +1036,23 @@ 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
+ * be passed to {@link (query:1)} 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 */
+/**
+ * `QueryFilterConstraint` is a helper union type that represents
+ * {@link QueryFieldFilterConstraint} and {@link QueryCompositeFilterConstraint}.
+ */
+export declare type QueryFilterConstraint = QueryFieldFilterConstraint | QueryCompositeFilterConstraint;
 /**
  * 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
+ * {@link limitToLast} and can then be passed to {@link (query:1)} to create a new
  * query instance that also contains this `QueryLimitConstraint`.
  */
 export declare class QueryLimitConstraint extends QueryConstraint {
@@ -1012,15 +1064,15 @@ export declare class QueryLimitConstraint extends QueryConstraint {
  * 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}
+ * {@link (startAt:1)}, {@link (startAfter:1)}, {@link (endBefore:1)}, {@link (endAt:1)},
+ * {@link limit} or {@link limitToLast} and can then be passed to {@link (query:1)}
  * 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
+ * {@link orderBy} and can then be passed to {@link (query:1)} 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
@@ -1063,7 +1115,7 @@ export declare class QuerySnapshot<T = DocumentData> {
  * 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
+ * {@link (startAfter:1)} and can then be passed to {@link (query:1)} to create a
  * new query instance that also contains this `QueryStartAtConstraint`.
  */
 export declare class QueryStartAtConstraint extends QueryConstraint {

package/dist/lite/index.node.cjs.js

@@ -14,7 +14,7 @@ function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'defau
 
 var nodeFetch__default = /*#__PURE__*/_interopDefaultLegacy(nodeFetch);
 
-const version$1 = "3.8.4";
+const version$1 = "3.9.0-20230314181055";
 
 /**
  * @license
@@ -67,7 +67,7 @@ User.GOOGLE_CREDENTIALS = new User('google-credentials-uid');
 User.FIRST_PARTY = new User('first-party-uid');
 User.MOCK_USER = new User('mock-user');
 
-const version = "9.17.2";
+const version = "9.18.0-20230314181055";
 
 /**
  * @license
@@ -1185,6 +1185,66 @@ function validatePositiveNumber(functionName, n) {
     }
 }
 
+/**
+ * @license
+ * Copyright 2023 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.
+ */
+/**
+ * The value returned from the most recent invocation of
+ * `generateUniqueDebugId()`, or null if it has never been invoked.
+ */
+let lastUniqueDebugId = null;
+/**
+ * Generates and returns an initial value for `lastUniqueDebugId`.
+ *
+ * The returned value is randomly selected from a range of integers that are
+ * represented as 8 hexadecimal digits. This means that (within reason) any
+ * numbers generated by incrementing the returned number by 1 will also be
+ * represented by 8 hexadecimal digits. This leads to all "IDs" having the same
+ * length when converted to a hexadecimal string, making reading logs containing
+ * these IDs easier to follow. And since the return value is randomly selected
+ * it will help to differentiate between logs from different executions.
+ */
+function generateInitialUniqueDebugId() {
+    const minResult = 0x10000000;
+    const maxResult = 0x90000000;
+    const resultRange = maxResult - minResult;
+    const resultOffset = Math.round(resultRange * Math.random());
+    return minResult + resultOffset;
+}
+/**
+ * Generates and returns a unique ID as a hexadecimal string.
+ *
+ * The returned ID is intended to be used in debug logging messages to help
+ * correlate log messages that may be spatially separated in the logs, but
+ * logically related. For example, a network connection could include the same
+ * "debug ID" string in all of its log messages to help trace a specific
+ * connection over time.
+ *
+ * @return the 10-character generated ID (e.g. "0xa1b2c3d4").
+ */
+function generateUniqueDebugId() {
+    if (lastUniqueDebugId === null) {
+        lastUniqueDebugId = generateInitialUniqueDebugId();
+    }
+    else {
+        lastUniqueDebugId++;
+    }
+    return '0x' + lastUniqueDebugId.toString(16);
+}
+
 /**
  * @license
  * Copyright 2020 Google LLC
@@ -1241,15 +1301,16 @@ class RestConnection {
         return false;
     }
     invokeRPC(rpcName, path, req, authToken, appCheckToken) {
+        const streamId = generateUniqueDebugId();
         const url = this.makeUrl(rpcName, path);
-        logDebug(LOG_TAG$3, 'Sending: ', url, req);
+        logDebug(LOG_TAG$3, `Sending RPC '${rpcName}' ${streamId}:`, url, req);
         const headers = {};
         this.modifyHeadersForRequest(headers, authToken, appCheckToken);
         return this.performRPCRequest(rpcName, url, headers, req).then(response => {
-            logDebug(LOG_TAG$3, 'Received: ', response);
+            logDebug(LOG_TAG$3, `Received RPC '${rpcName}' ${streamId}: `, response);
             return response;
         }, (err) => {
-            logWarn(LOG_TAG$3, `${rpcName} failed with error: `, err, 'url: ', url, 'request:', req);
+            logWarn(LOG_TAG$3, `RPC '${rpcName}' ${streamId} failed with error: `, err, 'url: ', url, 'request:', req);
             throw err;
         });
     }
@@ -5879,7 +5940,7 @@ class Query {
 }
 /**
  * A `CollectionReference` object can be used for adding documents, getting
- * document references, and querying for documents (using {@link query}).
+ * document references, and querying for documents (using {@link (query:1)}).
  */
 class CollectionReference extends Query {
     /** @hideconstructor */
@@ -7162,9 +7223,9 @@ class AppliableConstraint {
 /**
  * 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}, {@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
+ * {@link orderBy}, {@link (startAt:1)}, {@link (startAfter:1)}, {@link
+ * (endBefore:1)}, {@link (endAt:1)}, {@link limit}, {@link limitToLast} and
+ * can then be passed to {@link (query:1)} to create a new query instance that
  * also contains this `QueryConstraint`.
  */
 class QueryConstraint extends AppliableConstraint {
@@ -7185,7 +7246,7 @@ function query(query, queryConstraint, ...additionalQueryConstraints) {
  * 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
+ * be passed to {@link (query:1)} to create a new query instance that also contains
  * this `QueryFieldFilterConstraint`.
  */
 class QueryFieldFilterConstraint extends QueryConstraint {
@@ -7235,9 +7296,8 @@ function where(fieldPath, opStr, value) {
  * returned by a Firestore query by performing the logical OR or AND of multiple
  * {@link QueryFieldFilterConstraint}s or {@link QueryCompositeFilterConstraint}s.
  * `QueryCompositeFilterConstraint`s are created by invoking {@link or} or
- * {@link and} and can then be passed to {@link query} to create a new query
+ * {@link and} and can then be passed to {@link (query:1)} to create a new query
  * instance that also contains the `QueryCompositeFilterConstraint`.
- * @internal TODO remove this internal tag with OR Query support in the server
  */
 class QueryCompositeFilterConstraint extends AppliableConstraint {
     /**
@@ -7290,7 +7350,6 @@ class QueryCompositeFilterConstraint extends AppliableConstraint {
  * {@link QueryFilterConstraint}s to perform a disjunction for. These must be
  * created with calls to {@link where}, {@link or}, or {@link and}.
  * @returns The newly created {@link QueryCompositeFilterConstraint}.
- * @internal TODO remove this internal tag with OR Query support in the server
  */
 function or(...queryConstraints) {
     // Only support QueryFilterConstraints
@@ -7306,7 +7365,6 @@ function or(...queryConstraints) {
  * {@link QueryFilterConstraint}s to perform a conjunction for. These must be
  * created with calls to {@link where}, {@link or}, or {@link and}.
  * @returns The newly created {@link QueryCompositeFilterConstraint}.
- * @internal TODO remove this internal tag with OR Query support in the server
  */
 function and(...queryConstraints) {
     // Only support QueryFilterConstraints
@@ -7316,7 +7374,7 @@ function and(...queryConstraints) {
 /**
  * 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
+ * {@link orderBy} and can then be passed to {@link (query:1)} 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
@@ -7362,7 +7420,7 @@ function orderBy(fieldPath, directionStr = 'asc') {
  * 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
+ * {@link limitToLast} and can then be passed to {@link (query:1)} to create a new
  * query instance that also contains this `QueryLimitConstraint`.
  */
 class QueryLimitConstraint extends QueryConstraint {
@@ -7413,7 +7471,7 @@ function limitToLast(limit) {
  * 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
+ * {@link (startAfter:1)} and can then be passed to {@link (query:1)} to create a
  * new query instance that also contains this `QueryStartAtConstraint`.
  */
 class QueryStartAtConstraint extends QueryConstraint {
@@ -7448,7 +7506,7 @@ function startAfter(...docOrFields) {
  * 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
+ * {@link (endBefore:1)} and can then be passed to {@link (query:1)} to create a new
  * query instance that also contains this `QueryEndAtConstraint`.
  */
 class QueryEndAtConstraint extends QueryConstraint {