fix(firestore): type definitions (#8378)

---------

Co-authored-by: MichaelVerdon <[email protected]>
Co-authored-by: Mike Hardy <[email protected]>

Author: 3 people

packages/firestore/__tests__/firestore.test.ts

@@ -77,6 +77,8 @@ import firestore, {
   deleteAllPersistentCacheIndexes,
   disablePersistentCacheIndexAutoCreation,
   enablePersistentCacheIndexAutoCreation,
+  onSnapshotsInSync,
+  documentId,
 } from '../lib';
 
 const COLLECTION = 'firestore';
@@ -736,6 +738,14 @@ describe('Firestore', function () {
     it('`sum` is properly exposed to end user', function () {
       expect(sum).toBeDefined();
     });
+
+    it('`onSnapshotsInSync` is properly exposed to end user', function () {
+      expect(onSnapshotsInSync).toBeDefined();
+    });
+
+    it('`documentId` is properly exposed to end user', function () {
+      expect(documentId).toBeDefined();
+    });
   });
 
   describe('test `console.warn` is called for RNFB v8 API & not called for v9 API', function () {

packages/firestore/lib/modular/FieldPath.d.ts

@@ -11,3 +11,10 @@ export declare class FieldPath {
 
   isEqual(other: FieldPath): boolean;
 }
+
+/**
+ * Returns a special sentinel FieldPath to refer to the ID of a document
+ * It can be used in queries to sort or filter by the document ID
+ */
+
+export declare function documentId(): FieldPath;

packages/firestore/lib/modular/FieldPath.js

@@ -1,3 +1,7 @@
 import FirestoreFieldPath from '../FirestoreFieldPath';
 
 export const FieldPath = FirestoreFieldPath;
+
+export function documentId() {
+  return FieldPath.documentId();
+}

packages/firestore/lib/modular/index.d.ts

@@ -185,11 +185,11 @@ export function doc(
  * a document.
  * @returns The `DocumentReference` instance.
  */
-export function doc<T>(
-  reference: CollectionReference<T>,
+export declare function doc<AppModelType, DbModelType extends DocumentData>(
+  reference: CollectionReference<AppModelType, DbModelType>,
   path?: string,
   ...pathSegments: string[]
-): DocumentReference<T>;
+): DocumentReference<AppModelType, DbModelType>;
 
 /**
  * Gets a `DocumentReference` instance that refers to a document within
@@ -203,11 +203,11 @@ export function doc<T>(
  * a document.
  * @returns The `DocumentReference` instance.
  */
-export function doc(
-  reference: DocumentReference<unknown>,
+export declare function doc<AppModelType, DbModelType extends DocumentData>(
+  reference: DocumentReference<AppModelType, DbModelType>,
   path: string,
   ...pathSegments: string[]
-): DocumentReference<DocumentData>;
+): DocumentReference<DocumentData, DocumentData>;
 
 export function doc<T>(
   parent: Firestore | CollectionReference<T> | DocumentReference<unknown>,
@@ -231,7 +231,7 @@ export function collection(
   firestore: Firestore,
   path: string,
   ...pathSegments: string[]
-): CollectionReference<DocumentData>;
+): CollectionReference<DocumentData, DocumentData>;
 
 /**
  * Gets a `CollectionReference` instance that refers to a subcollection of
@@ -245,11 +245,29 @@ export function collection(
  * to a collection.
  * @returns The `CollectionReference` instance.
  */
-export function collection(
-  reference: CollectionReference<unknown>,
+export declare function collection<AppModelType, DbModelType extends DocumentData>(
+  reference: CollectionReference<AppModelType, DbModelType>,
   path: string,
   ...pathSegments: string[]
-): CollectionReference<DocumentData>;
+): CollectionReference<DocumentData, DocumentData>;
+
+/**
+ * Gets a `CollectionReference` instance that refers to a subcollection of
+ * `reference` at the specified relative path.
+ *
+ * @param reference - A reference to a document.
+ * @param path - A slash-separated path to a collection.
+ * @param pathSegments - Additional path segments to apply relative to the first
+ * argument.
+ * @throws If the final path has an even number of segments and does not point
+ * to a collection.
+ * @returns The `CollectionReference` instance.
+ */
+export declare function collection<AppModelType, DbModelType extends DocumentData>(
+  reference: DocumentReference<AppModelType, DbModelType>,
+  path: string,
+  ...pathSegments: string[]
+): CollectionReference<DocumentData, DocumentData>;
 
 /**
  * Gets a `CollectionReference` instance that refers to a subcollection of
@@ -302,7 +320,10 @@ export declare function refEqual<AppModelType, DbModelType extends DocumentData>
  * will be included. Cannot contain a slash.
  * @returns The created `Query`.
  */
-export function collectionGroup(firestore: Firestore, collectionId: string): Query<DocumentData>;
+export function collectionGroup(
+  firestore: Firestore,
+  collectionId: string,
+): Query<DocumentData, DocumentData>;
 
 /**
  * Writes to the document referred to by this `DocumentReference`. If the
@@ -383,10 +404,10 @@ export function updateDoc(
  * newly created document after it has been written to the backend (Note that it
  * won't resolve while you're offline).
  */
-export function addDoc<T>(
-  reference: CollectionReference<T>,
-  data: WithFieldValue<T>,
-): Promise<DocumentReference<T>>;
+export declare function addDoc<AppModelType, DbModelType extends DocumentData>(
+  reference: CollectionReference<AppModelType, DbModelType>,
+  data: WithFieldValue<AppModelType>,
+): Promise<DocumentReference<AppModelType, DbModelType>>;
 
 /**
  * Re-enables use of the network for this {@link Firestore} instance after a prior
@@ -701,7 +722,7 @@ export function loadBundle(
  * @param name - The name of the query.
  * @returns A named Query.
  */
-export function namedQuery(firestore: Firestore, name: string): Query<DocumentData>;
+export function namedQuery(firestore: Firestore, name: string): Promise<Query | null>;
 
 /**
  * Creates a write batch, used for performing multiple writes as a single

packages/firestore/lib/modular/query.d.ts

@@ -100,11 +100,11 @@ export type QueryNonFilterConstraint =
  * @throws if any of the provided query constraints cannot be combined with the
  * existing or new constraints.
  */
-export function query<T>(
-  query: Query<T>,
+export declare function query<AppModelType, DbModelType extends DocumentData>(
+  query: Query<AppModelType, DbModelType>,
   compositeFilter: QueryCompositeFilterConstraint,
   ...queryConstraints: QueryNonFilterConstraint[]
-): Query<T>;
+): Query<AppModelType, DbModelType>;
 
 /**
  * Creates a new immutable instance of {@link Query} that is extended to also
@@ -116,7 +116,10 @@ export function query<T>(
  * @throws if any of the provided query constraints cannot be combined with the
  * existing or new constraints.
  */
-export function query<T>(query: Query<T>, ...queryConstraints: IQueryConstraint[]): Query<T>;
+export declare function query<AppModelType, DbModelType extends DocumentData>(
+  query: Query<AppModelType, DbModelType>,
+  ...queryConstraints: QueryConstraint[]
+): Query<AppModelType, DbModelType>;
 
 export function query<T>(
   query: Query<T>,
@@ -173,7 +176,7 @@ export type OrderByDirection = 'desc' | 'asc';
  */
 export function orderBy(
   fieldPath: string | FieldPath,
-  directionStr: OrderByDirection = 'asc',
+  directionStr?: OrderByDirection = 'asc',
 ): QueryOrderByConstraint;
 
 /**
@@ -285,7 +288,9 @@ export declare function getDocFromServer<T>(
  *
  * @returns A `Promise` that will be resolved with the results of the query.
  */
-export function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
+export declare function getDocs<AppModelType, DbModelType extends DocumentData>(
+  query: Query<AppModelType, DbModelType>,
+): Promise<QuerySnapshot<AppModelType, DbModelType>>;
 
 /**
  * Executes the query and returns the results as a `QuerySnapshot` from cache.
@@ -294,15 +299,19 @@ export function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
  *
  * @returns A `Promise` that will be resolved with the results of the query.
  */
-export function getDocsFromCache<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
+export declare function getDocsFromCache<AppModelType, DbModelType extends DocumentData>(
+  query: Query<AppModelType, DbModelType>,
+): Promise<QuerySnapshot<AppModelType, DbModelType>>;
 
 /**
  * Executes the query and returns the results as a `QuerySnapshot` from the
  * server. Returns an error if the network is not available.
  *
  * @returns A `Promise` that will be resolved with the results of the query.
  */
-export function getDocsFromServer<T>(query: Query<T>): Promise<QuerySnapshot<T>>;
+export declare function getDocsFromServer<AppModelType, DbModelType extends DocumentData>(
+  query: Query<AppModelType, DbModelType>,
+): Promise<QuerySnapshot<AppModelType, DbModelType>>;
 
 /**
  * Deletes the document referred to by the specified `DocumentReference`.
@@ -311,53 +320,34 @@ export function getDocsFromServer<T>(query: Query<T>): Promise<QuerySnapshot<T>>
  * @returns A Promise resolved once the document has been successfully
  * deleted from the backend (note that it won't resolve while you're offline).
  */
-export function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;
+export declare function deleteDoc<AppModelType, DbModelType extends DocumentData>(
+  reference: DocumentReference<AppModelType, DbModelType>,
+): Promise<void>;
 
 /**
- * Creates a `QueryConstraint` with the specified ending point.
- *
- * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
- * allows you to choose arbitrary starting and ending points for your queries.
- *
- * The ending point is inclusive, so children with exactly the specified value
- * will be included in the query. The optional key argument can be used to
- * further limit the range of the query. If it is specified, then children that
- * have exactly the specified value must also have a key name less than or equal
- * to the specified key.
- *
- * You can read more about `endAt()` in
- * {@link https://firebase.google.com/docs/database/web/lists-of-data#filtering_data | Filtering data}.
+ * Creates a 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 value - The value to end at. The argument type depends on which
- * `orderBy*()` function was used in this query. Specify a value that matches
- * the `orderBy*()` type. When used in combination with `orderByKey()`, the
- * value must be a string.
- * @param key - The child key to end at, among the children with the previously
- * specified priority. This argument is only allowed if ordering by child,
- * value, or priority.
+ * @param fieldValues
  */
-export function endAt(value: number | string | boolean | null, key?: string): QueryConstraint;
+export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;
 
 /**
- * Creates a `QueryConstraint` with the specified ending point (exclusive).
- *
- * Using `startAt()`, `startAfter()`, `endBefore()`, `endAt()` and `equalTo()`
- * allows you to choose arbitrary starting and ending points for your queries.
- *
- * The ending point is exclusive. If only a value is provided, children
- * with a value less than the specified value will be included in the query.
- * If a key is specified, then children must have a value less than or equal
- * to the specified value and a key name less than the specified key.
+ * reates a 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
+ */
+export function endAt<AppModelType, DbModelType extends DocumentData>(
+  snapshot: DocumentSnapshot<AppModelType, DbModelType>,
+): QueryEndAtConstraint;
+
+/**
+ * Creates a 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 value - The value to end before. The argument type depends on which
- * `orderBy*()` function was used in this query. Specify a value that matches
- * the `orderBy*()` type. When used in combination with `orderByKey()`, the
- * value must be a string.
- * @param key - The child key to end before, among the children with the
- * previously specified priority. This argument is only allowed if ordering by
- * child, value, or priority.
+ * @param fieldValues
  */
-export function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint;
+export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;
 
 /**
  * Creates a new `QueryConstraint` that is limited to return only the last

packages/firestore/lib/modular/query.js

@@ -130,27 +130,25 @@ export function startAfter(...docOrFields) {
 }
 
 /**
- * @param {number | string | boolean | null} value
- * @param {string?} key
- * @returns {QueryConstraint}
+ * Creates a 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 {*} ...args Can be either a DocumentSnapshot or an array of field values.
  */
-export function endAt(value, key) {
-  if (!key) {
-    return new QueryConstraint('endAt', value);
-  }
-  return new QueryConstraint('endAt', value, key);
+
+export function endAt(...args) {
+  return new QueryConstraint('endAt', ...args);
 }
 
 /**
- * @param {number | string | boolean | null} value
- * @param {string?} key
- * @returns {QueryConstraint}
+ * Creates a 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
  */
-export function endBefore(value, key) {
-  if (!key) {
-    return new QueryConstraint('endBefore', value);
-  }
-  return new QueryConstraint('endBefore', value, key);
+
+export function endBefore(...fieldValues) {
+  return new QueryConstraint('endBefore', ...fieldValues);
 }
 
 /**