@react-native-firebase/firestore 23.8.6 → 24.0.0

package/lib/{FirestoreQuery.js → FirestoreQuery.ts}

@@ -16,37 +16,71 @@
  */
 
 import {
+  createDeprecationProxy,
+  filterModularArgument,
   isArray,
   isNull,
   isObject,
   isString,
   isUndefined,
-  filterModularArgument,
-  createDeprecationProxy,
 } from '@react-native-firebase/app/dist/module/common';
 import NativeError from '@react-native-firebase/app/dist/module/internal/NativeFirebaseError';
-import { FirestoreAggregateQuery } from './FirestoreAggregate';
-import FirestoreDocumentSnapshot from './FirestoreDocumentSnapshot';
-import FirestoreFieldPath, { fromDotSeparatedString } from './FirestoreFieldPath';
-import FirestoreQuerySnapshot from './FirestoreQuerySnapshot';
-import { parseSnapshotArgs } from './utils';
+import { AggregateQuery } from './FirestoreAggregate';
+import DocumentSnapshot from './FirestoreDocumentSnapshot';
+import FieldPath, { fromDotSeparatedString } from './FieldPath';
 import { _Filter, generateFilters } from './FirestoreFilter';
+import QueryModifiers from './FirestoreQueryModifiers';
+import QuerySnapshot, { type QuerySnapshotNativeData } from './FirestoreQuerySnapshot';
+import { parseSnapshotArgs, validateWithConverter } from './utils';
+
+import type FirestorePath from './FirestorePath';
+import type { DocumentData, FirestoreDataConverter } from './types/firestore';
+import type {
+  FirestoreInternal,
+  DocumentFieldValueInternal,
+  FirestoreSyncEventErrorInternal,
+  FirestoreSyncEventBodyInternal,
+} from './types/internal';
 
 let _id = 0;
 
-export default class FirestoreQuery {
-  constructor(firestore, collectionPath, modifiers, queryName) {
+export default class Query {
+  _firestore: FirestoreInternal;
+  _collectionPath: FirestorePath;
+  _modifiers: QueryModifiers;
+  _queryName: string | undefined;
+  _converter: FirestoreDataConverter<DocumentData, DocumentData> | null;
+
+  /** Satisfies Query<DocumentData, DocumentData> for AggregateQuerySnapshot and similar. */
+  readonly type = 'query' as const;
+
+  constructor(
+    firestore: FirestoreInternal,
+    collectionPath: FirestorePath,
+    modifiers: QueryModifiers,
+    queryName?: string,
+    converter?: FirestoreDataConverter<DocumentData, DocumentData> | null,
+  ) {
     this._firestore = firestore;
     this._collectionPath = collectionPath;
     this._modifiers = modifiers;
     this._queryName = queryName;
+    this._converter = converter ?? null;
   }
 
-  get firestore() {
+  get firestore(): FirestoreInternal {
     return this._firestore;
   }
 
-  _handleQueryCursor(cursor, docOrField, fields) {
+  get converter(): FirestoreDataConverter<DocumentData, DocumentData> | null {
+    return this._converter;
+  }
+
+  _handleQueryCursor(
+    cursor: 'startAt' | 'startAfter' | 'endAt' | 'endBefore',
+    docOrField: DocumentSnapshot | DocumentFieldValueInternal,
+    fields: DocumentFieldValueInternal[],
+  ): QueryModifiers {
     const modifiers = this._modifiers._copy();
 
     if (isUndefined(docOrField)) {
@@ -55,8 +89,7 @@ export default class FirestoreQuery {
       );
     }
 
-    // Handles cases where the first arg is a DocumentSnapshot
-    if (docOrField instanceof FirestoreDocumentSnapshot) {
+    if (docOrField instanceof DocumentSnapshot) {
       if (fields.length > 0) {
         throw new Error(
           `firebase.firestore().collection().${cursor}(*) Too many arguments provided. Expected DocumentSnapshot or list of field values.`,
@@ -72,40 +105,47 @@ export default class FirestoreQuery {
       }
 
       const currentOrders = modifiers.orders;
-
-      const values = [];
+      const values: DocumentFieldValueInternal[] = [];
 
       for (let i = 0; i < currentOrders.length; i++) {
-        const order = currentOrders[i];
-        //skip if fieldPath is '__name__'
-        if (order.fieldPath === '__name__') {
+        const order = currentOrders[i]!;
+        const pathStr = Array.isArray(order.fieldPath)
+          ? order.fieldPath.join('.')
+          : String(order.fieldPath);
+        if (pathStr === '__name__') {
           continue;
         }
 
-        const value = documentSnapshot.get(order.fieldPath);
+        const value = documentSnapshot.get(
+          Array.isArray(order.fieldPath)
+            ? new FieldPath(...order.fieldPath)
+            : (order.fieldPath as string | FieldPath),
+        );
 
         if (value === undefined) {
           throw new Error(
-            `firebase.firestore().collection().${cursor}(*) You are trying to start or end a query using a document for which the field '${order.fieldPath}' (used as the orderBy) does not exist.`,
+            `firebase.firestore().collection().${cursor}(*) You are trying to start or end a query using a document for which the field '${pathStr}' (used as the orderBy) does not exist.`,
           );
         }
 
         values.push(value);
       }
 
-      // Based on https://github.com/invertase/react-native-firebase/issues/2854#issuecomment-552986650
       if (modifiers._orders.length) {
-        const lastOrder = modifiers._orders[modifiers._orders.length - 1];
-        //push '__name__' field only if not present already
-        if (lastOrder.fieldPath !== '__name__') {
+        const lastOrder = modifiers._orders[modifiers._orders.length - 1]!;
+        const lastPathStr =
+          lastOrder.fieldPath instanceof FieldPath
+            ? lastOrder.fieldPath._toPath()
+            : String(lastOrder.fieldPath);
+        if (lastPathStr !== '__name__') {
           modifiers._orders.push({
-            fieldPath: '__name__',
+            fieldPath: new FieldPath('__name__'),
             direction: lastOrder.direction,
           });
         }
       } else {
         modifiers._orders.push({
-          fieldPath: '__name__',
+          fieldPath: new FieldPath('__name__'),
           direction: 'ASCENDING',
         });
       }
@@ -119,10 +159,6 @@ export default class FirestoreQuery {
       return modifiers.setFieldsCursor(cursor, values);
     }
 
-    /**
-     * Assumes list of field values to query by. Orders must be of equal length.
-     */
-
     const allFields = [docOrField].concat(fields);
 
     if (allFields.length > modifiers.orders.length) {
@@ -134,40 +170,47 @@ export default class FirestoreQuery {
     return modifiers.setFieldsCursor(cursor, allFields);
   }
 
-  count() {
+  count(): ReturnType<typeof createDeprecationProxy> {
     return createDeprecationProxy(
-      new FirestoreAggregateQuery(this._firestore, this, this._collectionPath, this._modifiers),
+      new AggregateQuery(this._firestore, this, this._collectionPath, this._modifiers),
     );
   }
 
-  countFromServer() {
-    // deprecation warning called in count()
+  countFromServer(): ReturnType<Query['count']> {
     return this.count();
   }
 
-  endAt(docOrField, ...fields) {
+  endAt(
+    docOrField: DocumentSnapshot | DocumentFieldValueInternal,
+    ...fields: DocumentFieldValueInternal[]
+  ): ReturnType<typeof createDeprecationProxy> {
     return createDeprecationProxy(
-      new FirestoreQuery(
+      new Query(
         this._firestore,
         this._collectionPath,
         this._handleQueryCursor('endAt', docOrField, filterModularArgument(fields)),
         this._queryName,
+        this._converter,
       ),
     );
   }
 
-  endBefore(docOrField, ...fields) {
+  endBefore(
+    docOrField: DocumentSnapshot | DocumentFieldValueInternal,
+    ...fields: DocumentFieldValueInternal[]
+  ): ReturnType<typeof createDeprecationProxy> {
     return createDeprecationProxy(
-      new FirestoreQuery(
+      new Query(
         this._firestore,
         this._collectionPath,
         this._handleQueryCursor('endBefore', docOrField, filterModularArgument(fields)),
         this._queryName,
+        this._converter,
       ),
     );
   }
 
-  get(options) {
+  get(options?: { source?: 'default' | 'server' | 'cache' }): Promise<QuerySnapshot> {
     if (!isUndefined(options) && !isObject(options)) {
       throw new Error(
         "firebase.firestore().collection().get(*) 'options' must be an object is provided.",
@@ -196,7 +239,15 @@ export default class FirestoreQuery {
           this._modifiers.options,
           options,
         )
-        .then(data => new FirestoreQuerySnapshot(this._firestore, this, data));
+        .then(
+          (data: unknown) =>
+            new QuerySnapshot(
+              this._firestore,
+              this,
+              data as QuerySnapshotNativeData,
+              this._converter,
+            ),
+        );
     }
 
     this._modifiers.validatelimitToLast();
@@ -210,30 +261,36 @@ export default class FirestoreQuery {
         this._modifiers.options,
         options,
       )
-      .then(data => new FirestoreQuerySnapshot(this._firestore, this, data));
+      .then(
+        (data: unknown) =>
+          new QuerySnapshot(
+            this._firestore,
+            this,
+            data as QuerySnapshotNativeData,
+            this._converter,
+          ),
+      );
   }
 
-  isEqual(other) {
-    if (!(other instanceof FirestoreQuery)) {
+  isEqual(other: Query): boolean {
+    if (!(other instanceof Query)) {
       throw new Error(
         "firebase.firestore().collection().isEqual(*) 'other' expected a Query instance.",
       );
     }
 
-    // Carry out lightweight checks first
     if (
       this.firestore.app.name !== other.firestore.app.name ||
       this._modifiers.type !== other._modifiers.type ||
       this._modifiers.filters.length !== other._modifiers.filters.length ||
       this._modifiers.orders.length !== other._modifiers.orders.length ||
       this._collectionPath.relativeName !== other._collectionPath.relativeName ||
+      this._converter !== other._converter ||
       Object.keys(this._modifiers.options).length !== Object.keys(other._modifiers.options).length
     ) {
       return false;
     }
 
-    // Carry out potentially expensive checks
-    // noinspection RedundantIfStatementJS
     if (
       JSON.stringify(this._modifiers.filters) !== JSON.stringify(other._modifiers.filters) ||
       JSON.stringify(this._modifiers.orders) !== JSON.stringify(other._modifiers.orders) ||
@@ -245,7 +302,7 @@ export default class FirestoreQuery {
     return true;
   }
 
-  limit(limit) {
+  limit(limit: number): ReturnType<typeof createDeprecationProxy> {
     if (this._modifiers.isValidLimit(limit)) {
       throw new Error(
         "firebase.firestore().collection().limit(*) 'limit' must be a positive integer value.",
@@ -255,11 +312,11 @@ export default class FirestoreQuery {
     const modifiers = this._modifiers._copy().limit(limit);
 
     return createDeprecationProxy(
-      new FirestoreQuery(this._firestore, this._collectionPath, modifiers, this._queryName),
+      new Query(this._firestore, this._collectionPath, modifiers, this._queryName, this._converter),
     );
   }
 
-  limitToLast(limitToLast) {
+  limitToLast(limitToLast: number): ReturnType<typeof createDeprecationProxy> {
     if (this._modifiers.isValidLimitToLast(limitToLast)) {
       throw new Error(
         "firebase.firestore().collection().limitToLast(*) 'limitToLast' must be a positive integer value.",
@@ -269,15 +326,15 @@ export default class FirestoreQuery {
     const modifiers = this._modifiers._copy().limitToLast(limitToLast);
 
     return createDeprecationProxy(
-      new FirestoreQuery(this._firestore, this._collectionPath, modifiers, this._queryName),
+      new Query(this._firestore, this._collectionPath, modifiers, this._queryName, this._converter),
     );
   }
 
-  onSnapshot(...args) {
-    let snapshotListenOptions;
-    let callback;
-    let onNext;
-    let onError;
+  onSnapshot(...args: unknown[]): () => void {
+    let snapshotListenOptions: { includeMetadataChanges?: boolean };
+    let callback: (snapshot: QuerySnapshot | null, error: Error | null) => void;
+    let onNext: (snapshot: QuerySnapshot) => void;
+    let onError: (error: Error) => void;
 
     this._modifiers.validatelimitToLast();
 
@@ -288,15 +345,15 @@ export default class FirestoreQuery {
       onNext = options.onNext;
       onError = options.onError;
     } catch (e) {
-      throw new Error(`firebase.firestore().collection().onSnapshot(*) ${e.message}`);
+      throw new Error(`firebase.firestore().collection().onSnapshot(*) ${(e as Error).message}`);
     }
 
-    function handleSuccess(querySnapshot) {
+    function handleSuccess(querySnapshot: QuerySnapshot): void {
       callback(querySnapshot, null);
       onNext(querySnapshot);
     }
 
-    function handleError(error) {
+    function handleError(error: Error): void {
       callback(null, error);
       onError(error);
     }
@@ -305,21 +362,23 @@ export default class FirestoreQuery {
 
     const onSnapshotSubscription = this._firestore.emitter.addListener(
       this._firestore.eventNameForApp(`firestore_collection_sync_event:${listenerId}`),
-      event => {
-        if (event.body.error) {
-          handleError(NativeError.fromEvent(event.body.error, 'firestore'));
+      (event: { body: FirestoreSyncEventBodyInternal }) => {
+        const body = event.body as {
+          error?: FirestoreSyncEventErrorInternal;
+          snapshot?: QuerySnapshotNativeData;
+        };
+        if (body.error) {
+          handleError(NativeError.fromEvent(body.error, 'firestore'));
         } else {
-          const querySnapshot = new FirestoreQuerySnapshot(
-            this._firestore,
-            this,
-            event.body.snapshot,
-          );
+          const snapshot = body.snapshot;
+          if (!snapshot) return;
+          const querySnapshot = new QuerySnapshot(this._firestore, this, snapshot, this._converter);
           handleSuccess(querySnapshot);
         }
       },
     );
 
-    const unsubscribe = () => {
+    const unsubscribe = (): void => {
       onSnapshotSubscription.remove();
       this._firestore.native.collectionOffSnapshot(listenerId);
     };
@@ -349,20 +408,25 @@ export default class FirestoreQuery {
     return unsubscribe;
   }
 
-  orderBy(fieldPath, directionStr) {
-    if (!isString(fieldPath) && !(fieldPath instanceof FirestoreFieldPath)) {
+  orderBy(
+    fieldPath: string | FieldPath,
+    directionStr?: string,
+  ): ReturnType<typeof createDeprecationProxy> {
+    if (!isString(fieldPath) && !(fieldPath instanceof FieldPath)) {
       throw new Error(
         "firebase.firestore().collection().orderBy(*) 'fieldPath' must be a string or instance of FieldPath.",
       );
     }
 
-    let path;
+    let path: FieldPath;
 
     if (isString(fieldPath)) {
       try {
         path = fromDotSeparatedString(fieldPath);
       } catch (e) {
-        throw new Error(`firebase.firestore().collection().orderBy(*) 'fieldPath' ${e.message}.`);
+        throw new Error(
+          `firebase.firestore().collection().orderBy(*) 'fieldPath' ${(e as Error).message}.`,
+        );
       }
     } else {
       path = fieldPath;
@@ -391,40 +455,52 @@ export default class FirestoreQuery {
     try {
       modifiers.validateOrderBy();
     } catch (e) {
-      throw new Error(`firebase.firestore().collection().orderBy() ${e.message}`);
+      throw new Error(`firebase.firestore().collection().orderBy() ${(e as Error).message}`);
     }
 
     return createDeprecationProxy(
-      new FirestoreQuery(this._firestore, this._collectionPath, modifiers, this._queryName),
+      new Query(this._firestore, this._collectionPath, modifiers, this._queryName, this._converter),
     );
   }
 
-  startAfter(docOrField, ...fields) {
+  startAfter(
+    docOrField: DocumentSnapshot | DocumentFieldValueInternal,
+    ...fields: DocumentFieldValueInternal[]
+  ): ReturnType<typeof createDeprecationProxy> {
     return createDeprecationProxy(
-      new FirestoreQuery(
+      new Query(
         this._firestore,
         this._collectionPath,
         this._handleQueryCursor('startAfter', docOrField, filterModularArgument(fields)),
         this._queryName,
+        this._converter,
       ),
     );
   }
 
-  startAt(docOrField, ...fields) {
+  startAt(
+    docOrField: DocumentSnapshot | DocumentFieldValueInternal,
+    ...fields: DocumentFieldValueInternal[]
+  ): ReturnType<typeof createDeprecationProxy> {
     return createDeprecationProxy(
-      new FirestoreQuery(
+      new Query(
         this._firestore,
         this._collectionPath,
         this._handleQueryCursor('startAt', docOrField, filterModularArgument(fields)),
         this._queryName,
+        this._converter,
       ),
     );
   }
 
-  where(fieldPathOrFilter, opStr, value) {
+  where(
+    fieldPathOrFilter: string | FieldPath | _Filter,
+    opStr?: string,
+    value?: DocumentFieldValueInternal,
+  ): ReturnType<typeof createDeprecationProxy> {
     if (
       !isString(fieldPathOrFilter) &&
-      !(fieldPathOrFilter instanceof FirestoreFieldPath) &&
+      !(fieldPathOrFilter instanceof FieldPath) &&
       !(fieldPathOrFilter instanceof _Filter)
     ) {
       throw new Error(
@@ -432,77 +508,109 @@ export default class FirestoreQuery {
       );
     }
 
-    let modifiers;
+    let modifiers: QueryModifiers;
+
     if (fieldPathOrFilter instanceof _Filter && fieldPathOrFilter.queries) {
-      //AND or OR filter
       const filters = generateFilters(fieldPathOrFilter, this._modifiers);
       modifiers = this._modifiers._copy().filterWhere(filters);
     } else {
+      let path: FieldPath;
+      let op = opStr;
+      let val = value;
+
       if (fieldPathOrFilter instanceof _Filter) {
-        // Standard Filter. Usual path.
-        opStr = fieldPathOrFilter.operator;
-        value = fieldPathOrFilter.value;
-        fieldPathOrFilter = fieldPathOrFilter.fieldPath;
+        op = fieldPathOrFilter.operator as string;
+        val = fieldPathOrFilter.value;
+        fieldPathOrFilter = fieldPathOrFilter.fieldPath as FieldPath;
       }
-      let path;
 
       if (isString(fieldPathOrFilter)) {
         try {
           path = fromDotSeparatedString(fieldPathOrFilter);
         } catch (e) {
-          throw new Error(`firebase.firestore().collection().where(*) 'fieldPath' ${e.message}.`);
+          throw new Error(
+            `firebase.firestore().collection().where(*) 'fieldPath' ${(e as Error).message}.`,
+          );
         }
       } else {
         path = fieldPathOrFilter;
       }
 
-      if (!this._modifiers.isValidOperator(opStr)) {
+      if (!this._modifiers.isValidOperator(op!)) {
         throw new Error(
           "firebase.firestore().collection().where(_, *) 'opStr' is invalid. Expected one of '==', '>', '>=', '<', '<=', '!=', 'array-contains', 'not-in', 'array-contains-any' or 'in'.",
         );
       }
 
-      if (isUndefined(value)) {
+      if (isUndefined(val)) {
         throw new Error(
           "firebase.firestore().collection().where(_, _, *) 'value' argument expected.",
         );
       }
 
       if (
-        isNull(value) &&
-        !this._modifiers.isEqualOperator(opStr) &&
-        !this._modifiers.isNotEqualOperator(opStr)
+        isNull(val) &&
+        !this._modifiers.isEqualOperator(op!) &&
+        !this._modifiers.isNotEqualOperator(op!)
       ) {
         throw new Error(
           "firebase.firestore().collection().where(_, _, *) 'value' is invalid. You can only perform equals comparisons on null",
         );
       }
 
-      if (this._modifiers.isInOperator(opStr)) {
-        if (!isArray(value) || !value.length) {
+      if (this._modifiers.isInOperator(op!)) {
+        if (!isArray(val) || !(val as DocumentFieldValueInternal[]).length) {
           throw new Error(
-            `firebase.firestore().collection().where(_, _, *) 'value' is invalid. A non-empty array is required for '${opStr}' filters.`,
+            `firebase.firestore().collection().where(_, _, *) 'value' is invalid. A non-empty array is required for '${op}' filters.`,
           );
         }
 
-        if (value.length > 30) {
+        if ((val as DocumentFieldValueInternal[]).length > 30) {
           throw new Error(
-            `firebase.firestore().collection().where(_, _, *) 'value' is invalid. '${opStr}' filters support a maximum of 30 elements in the value array.`,
+            `firebase.firestore().collection().where(_, _, *) 'value' is invalid. '${op}' filters support a maximum of 30 elements in the value array.`,
           );
         }
       }
 
-      modifiers = this._modifiers._copy().where(path, opStr, value);
+      modifiers = this._modifiers._copy().where(path, op!, val);
     }
 
     try {
       modifiers.validateWhere();
     } catch (e) {
-      throw new Error(`firebase.firestore().collection().where() ${e.message}`);
+      throw new Error(`firebase.firestore().collection().where() ${(e as Error).message}`);
     }
 
     return createDeprecationProxy(
-      new FirestoreQuery(this._firestore, this._collectionPath, modifiers, this._queryName),
+      new Query(this._firestore, this._collectionPath, modifiers, this._queryName, this._converter),
+    );
+  }
+
+  withConverter(
+    converter: FirestoreDataConverter<DocumentData, DocumentData> | null | unknown,
+  ): Query {
+    if (isUndefined(converter) || isNull(converter)) {
+      return new Query(
+        this._firestore,
+        this._collectionPath,
+        this._modifiers,
+        this._queryName,
+        null,
+      );
+    }
+
+    try {
+      validateWithConverter(converter);
+    } catch (e) {
+      throw new Error(`firebase.firestore().collection().withConverter() ${(e as Error).message}`);
+    }
+
+    return new Query(
+      this._firestore,
+      this._collectionPath,
+      this._modifiers,
+      this._queryName,
+      converter as FirestoreDataConverter<DocumentData, DocumentData>,
     );
   }
 }