@react-native-firebase/firestore 23.8.8 → 24.0.0

package/lib/FirestoreDocumentReference.ts

@@ -0,0 +1,310 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library 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.
+ *
+ */
+
+import {
+  isObject,
+  isString,
+  isUndefined,
+  isNull,
+  createDeprecationProxy,
+  filterModularArgument,
+} from '@react-native-firebase/app/dist/module/common';
+import NativeError from '@react-native-firebase/app/dist/module/internal/NativeFirebaseError';
+import {
+  parseSetOptions,
+  parseSnapshotArgs,
+  parseUpdateArgs,
+  validateWithConverter,
+  applyFirestoreDataConverter,
+} from './utils';
+import { buildNativeMap, provideDocumentReferenceClass } from './utils/serialize';
+
+import type FirestoreCollectionReferenceClass from './FirestoreCollectionReference';
+import type DocumentSnapshot from './FirestoreDocumentSnapshot';
+import type { FirestoreInternal, FirestoreSyncEventBodyInternal } from './types/internal';
+import type { DocumentSnapshotNativeData } from './FirestoreDocumentSnapshot';
+import type FirestorePath from './FirestorePath';
+import type { DocumentData, FirestoreDataConverter } from './types/firestore';
+
+let FirestoreCollectionReference:
+  | (new (
+      firestore: FirestoreInternal,
+      path: FirestorePath,
+      converter?: FirestoreDataConverter<DocumentData, DocumentData> | null,
+    ) => FirestoreCollectionReferenceClass)
+  | null = null;
+
+export function provideCollectionReferenceClass(
+  collectionReference: new (
+    firestore: FirestoreInternal,
+    path: FirestorePath,
+    converter?: FirestoreDataConverter<DocumentData, DocumentData> | null,
+  ) => FirestoreCollectionReferenceClass,
+): void {
+  FirestoreCollectionReference = collectionReference;
+}
+
+let FirestoreDocumentSnapshotClass:
+  | (new (
+      firestore: FirestoreInternal,
+      data: DocumentSnapshotNativeData,
+      converter: FirestoreDataConverter<DocumentData, DocumentData> | null,
+    ) => DocumentSnapshot)
+  | null = null;
+
+export function provideDocumentSnapshotClass(
+  documentSnapshot: new (
+    firestore: FirestoreInternal,
+    data: DocumentSnapshotNativeData,
+    converter: FirestoreDataConverter<DocumentData, DocumentData> | null,
+  ) => DocumentSnapshot,
+): void {
+  FirestoreDocumentSnapshotClass = documentSnapshot;
+}
+
+let _id = 0;
+
+export default class DocumentReference {
+  _firestore: FirestoreInternal;
+  _documentPath: FirestorePath;
+  _converter: FirestoreDataConverter<DocumentData, DocumentData> | null;
+
+  constructor(firestore: FirestoreInternal, documentPath: FirestorePath, converter?: unknown) {
+    this._firestore = firestore;
+    this._documentPath = documentPath;
+    this._converter = (converter === undefined ? null : converter) as FirestoreDataConverter<
+      DocumentData,
+      DocumentData
+    > | null;
+  }
+
+  get firestore(): FirestoreInternal {
+    return this._firestore;
+  }
+
+  get converter(): unknown {
+    return this._converter;
+  }
+
+  get id(): string {
+    return this._documentPath.id;
+  }
+
+  get parent(): FirestoreCollectionReferenceClass {
+    const parentPath = this._documentPath.parent();
+    return new FirestoreCollectionReference!(this._firestore, parentPath!, this._converter);
+  }
+
+  get path(): string {
+    return this._documentPath.relativeName;
+  }
+
+  collection(collectionPath: string): FirestoreCollectionReferenceClass {
+    if (!isString(collectionPath)) {
+      throw new Error(
+        "firebase.firestore().doc().collection(*) 'collectionPath' must be a string value.",
+      );
+    }
+
+    if (collectionPath === '') {
+      throw new Error(
+        "firebase.firestore().doc().collection(*) 'collectionPath' must be a non-empty string.",
+      );
+    }
+
+    const path = this._documentPath.child(collectionPath);
+
+    if (!path.isCollection) {
+      throw new Error(
+        "firebase.firestore().doc().collection(*) 'collectionPath' must point to a collection.",
+      );
+    }
+
+    return new FirestoreCollectionReference!(this._firestore, path);
+  }
+
+  delete(): Promise<void> {
+    return this._firestore.native.documentDelete(this.path);
+  }
+
+  get(options?: { source?: 'default' | 'server' | 'cache' }): Promise<DocumentSnapshot> {
+    if (!isUndefined(options) && !isObject(options)) {
+      throw new Error("firebase.firestore().doc().get(*) 'options' must be an object is provided.");
+    }
+
+    if (
+      options &&
+      options.source &&
+      options.source !== 'default' &&
+      options.source !== 'server' &&
+      options.source !== 'cache'
+    ) {
+      throw new Error(
+        "firebase.firestore().doc().get(*) 'options' GetOptions.source must be one of 'default', 'server' or 'cache'.",
+      );
+    }
+
+    return this._firestore.native
+      .documentGet(this.path, options)
+      .then(
+        (data: unknown) =>
+          createDeprecationProxy(
+            new FirestoreDocumentSnapshotClass!(
+              this._firestore,
+              data as DocumentSnapshotNativeData,
+              this._converter,
+            ),
+          ) as DocumentSnapshot,
+      );
+  }
+
+  isEqual(other: DocumentReference): boolean {
+    if (!(other instanceof DocumentReference)) {
+      throw new Error(
+        "firebase.firestore().doc().isEqual(*) 'other' expected a DocumentReference instance.",
+      );
+    }
+
+    return !(
+      this.path !== other.path ||
+      this.firestore.app.name !== other.firestore.app.name ||
+      this.firestore.app.options.projectId !== other.firestore.app.options.projectId ||
+      this.converter !== other.converter
+    );
+  }
+
+  onSnapshot(...args: unknown[]): () => void {
+    let snapshotListenOptions: { includeMetadataChanges?: boolean };
+    let callback: (snapshot: DocumentSnapshot | null, error: Error | null) => void;
+    let onNext: (snapshot: DocumentSnapshot) => void;
+    let onError: (error: Error) => void;
+
+    try {
+      const options = parseSnapshotArgs(args);
+      snapshotListenOptions = options.snapshotListenOptions;
+      callback = options.callback;
+      onNext = options.onNext;
+      onError = options.onError;
+    } catch (e) {
+      throw new Error(`firebase.firestore().doc().onSnapshot(*) ${(e as Error).message}`);
+    }
+
+    function handleSuccess(documentSnapshot: DocumentSnapshot): void {
+      callback(documentSnapshot, null);
+      onNext(documentSnapshot);
+    }
+
+    function handleError(error: Error): void {
+      callback(null, error);
+      onError(error);
+    }
+
+    const listenerId = _id++;
+
+    const onSnapshotSubscription = this._firestore.emitter.addListener(
+      this._firestore.eventNameForApp(`firestore_document_sync_event:${listenerId}`),
+      (event: { body: FirestoreSyncEventBodyInternal }) => {
+        if (event.body.error) {
+          handleError(NativeError.fromEvent(event.body.error, 'firestore'));
+        } else {
+          const snapshot = event.body.snapshot;
+          if (!snapshot) return;
+          const documentSnapshot = createDeprecationProxy(
+            new FirestoreDocumentSnapshotClass!(this._firestore, snapshot, this._converter),
+          );
+          handleSuccess(documentSnapshot);
+        }
+      },
+    );
+
+    const unsubscribe = (): void => {
+      onSnapshotSubscription.remove();
+      this._firestore.native.documentOffSnapshot(listenerId);
+    };
+
+    this._firestore.native.documentOnSnapshot(this.path, listenerId, snapshotListenOptions);
+
+    return unsubscribe;
+  }
+
+  set(data: unknown, options?: unknown): Promise<void> {
+    let setOptions: ReturnType<typeof parseSetOptions>;
+    try {
+      setOptions = parseSetOptions(options);
+    } catch (e) {
+      throw new Error(`firebase.firestore().doc().set(_, *) ${(e as Error).message}.`);
+    }
+
+    let converted = data;
+    try {
+      converted = applyFirestoreDataConverter(data, this._converter, setOptions);
+    } catch (e) {
+      throw new Error(
+        `firebase.firestore().doc().set(*) 'withConverter.toFirestore' threw an error: ${(e as Error).message}.`,
+      );
+    }
+
+    if (!isObject(converted)) {
+      throw new Error("firebase.firestore().doc().set(*) 'data' must be an object.");
+    }
+
+    return this._firestore.native.documentSet(
+      this.path,
+      buildNativeMap(converted, this._firestore._settings.ignoreUndefinedProperties),
+      setOptions,
+    );
+  }
+
+  update(...args: unknown[]): Promise<void> {
+    const updatedArgs = filterModularArgument(args);
+    if (updatedArgs.length === 0) {
+      throw new Error(
+        'firebase.firestore().doc().update(*) expected at least 1 argument but was called with 0 arguments.',
+      );
+    }
+
+    let data: Record<string, unknown>;
+    try {
+      data = parseUpdateArgs(updatedArgs);
+    } catch (e) {
+      throw new Error(`firebase.firestore().doc().update(*) ${(e as Error).message}`);
+    }
+
+    return this._firestore.native.documentUpdate(
+      this.path,
+      buildNativeMap(data, this._firestore._settings.ignoreUndefinedProperties),
+    );
+  }
+
+  withConverter(
+    converter: FirestoreDataConverter<DocumentData, DocumentData> | null,
+  ): DocumentReference {
+    if (isUndefined(converter) || isNull(converter)) {
+      return new DocumentReference(this._firestore, this._documentPath, null);
+    }
+
+    try {
+      validateWithConverter(converter);
+    } catch (e) {
+      throw new Error(`firebase.firestore().doc().withConverter() ${(e as Error).message}`);
+    }
+
+    return new DocumentReference(this._firestore, this._documentPath, converter);
+  }
+}
+
+provideDocumentReferenceClass(DocumentReference);

package/lib/FirestoreDocumentSnapshot.ts

@@ -0,0 +1,149 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library 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.
+ *
+ */
+
+import { isString } from '@react-native-firebase/app/dist/module/common';
+import DocumentReference, { provideDocumentSnapshotClass } from './FirestoreDocumentReference';
+import FieldPath, { fromDotSeparatedString } from './FieldPath';
+import FirestorePath from './FirestorePath';
+import SnapshotMetadata from './FirestoreSnapshotMetadata';
+import type { SnapshotOptions } from './types/firestore';
+import { extractFieldPathData } from './utils';
+import { parseNativeMap } from './utils/serialize';
+import type {
+  FirestoreInternal,
+  ConverterWithFromFirestoreInternal,
+  DocumentFieldValueInternal,
+} from './types/internal';
+import type {
+  DocumentData,
+  DocumentSnapshot as DocumentSnapshotDeclare,
+  FirestoreDataConverter,
+} from './types/firestore';
+
+export interface DocumentSnapshotNativeData {
+  path: string;
+  data?: unknown;
+  metadata?: [boolean, boolean];
+  exists?: boolean;
+}
+
+export default class DocumentSnapshot {
+  _firestore: FirestoreInternal;
+  _nativeData: DocumentSnapshotNativeData;
+  _data: Record<string, unknown> | undefined;
+  _metadata: SnapshotMetadata;
+  _ref: DocumentReference;
+  _exists: boolean;
+  _converter: FirestoreDataConverter<DocumentData, DocumentData> | null;
+
+  constructor(
+    firestore: FirestoreInternal,
+    nativeData: DocumentSnapshotNativeData,
+    converter: FirestoreDataConverter<DocumentData, DocumentData> | null,
+  ) {
+    this._firestore = firestore;
+    this._nativeData = nativeData;
+    this._data = parseNativeMap(firestore, nativeData.data as Record<string, unknown> | undefined);
+    this._metadata = new SnapshotMetadata(nativeData.metadata ?? [false, false]);
+    this._ref = new DocumentReference(firestore, FirestorePath.fromName(nativeData.path));
+    this._exists = nativeData.exists ?? false;
+    this._converter = converter;
+  }
+
+  get id(): string {
+    return this._ref.id;
+  }
+
+  get metadata(): SnapshotMetadata {
+    return this._metadata;
+  }
+
+  get ref(): DocumentReference {
+    return this._ref;
+  }
+
+  exists(): boolean {
+    return this._exists;
+  }
+
+  data(options?: SnapshotOptions): DocumentData | undefined {
+    if (this._converter) {
+      try {
+        return (this._converter as ConverterWithFromFirestoreInternal).fromFirestore(
+          new DocumentSnapshot(
+            this._firestore,
+            this._nativeData,
+            null,
+          ) as unknown as DocumentSnapshotDeclare<DocumentData, DocumentData>,
+          options,
+        ) as DocumentData;
+      } catch (e) {
+        throw new Error(
+          `firebase.firestore() DocumentSnapshot.data(*) 'withConverter.fromFirestore' threw an error: ${(e as Error).message}.`,
+        );
+      }
+    }
+    return this._data;
+  }
+
+  get(fieldPath: string | FieldPath, _options?: SnapshotOptions): DocumentFieldValueInternal {
+    if (!isString(fieldPath) && !(fieldPath instanceof FieldPath)) {
+      throw new Error(
+        "firebase.firestore() DocumentSnapshot.get(*) 'fieldPath' expected type string or FieldPath.",
+      );
+    }
+
+    let path: FieldPath;
+
+    if (isString(fieldPath)) {
+      try {
+        path = fromDotSeparatedString(fieldPath);
+      } catch (e) {
+        throw new Error(
+          `firebase.firestore() DocumentSnapshot.get(*) 'fieldPath' ${(e as Error).message}.`,
+        );
+      }
+    } else {
+      path = fieldPath;
+    }
+
+    return extractFieldPathData(this._data, path._segments) as DocumentFieldValueInternal;
+  }
+
+  isEqual(other: DocumentSnapshot): boolean {
+    if (!(other instanceof DocumentSnapshot)) {
+      throw new Error(
+        "firebase.firestore() DocumentSnapshot.isEqual(*) 'other' expected a DocumentSnapshot instance.",
+      );
+    }
+
+    if (
+      this.exists() !== other.exists() ||
+      !this.metadata.isEqual(other.metadata) ||
+      !this.ref.isEqual(other.ref)
+    ) {
+      return false;
+    }
+
+    const thisData = JSON.stringify(this.data());
+    const otherData = JSON.stringify(other.data());
+
+    return thisData === otherData;
+  }
+}
+
+provideDocumentSnapshotClass(DocumentSnapshot);

package/lib/FirestoreFilter.ts

@@ -0,0 +1,232 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library 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.
+ *
+ */
+
+import {
+  isArray,
+  isNull,
+  isString,
+  isUndefined,
+} from '@react-native-firebase/app/dist/module/common';
+import { fromDotSeparatedString } from './FieldPath';
+import { OPERATORS } from './FirestoreQueryModifiers';
+import { generateNativeData } from './utils/serialize';
+import type FieldPath from './FieldPath';
+import type { Primitive } from './types/firestore';
+
+const AND_QUERY = 'AND';
+const OR_QUERY = 'OR';
+
+type FilterOperator = typeof AND_QUERY | typeof OR_QUERY;
+type FieldFilterOperator = keyof typeof OPERATORS;
+
+/** Value allowed in a filter (primitive, object, or array for in/array-contains-any). */
+type FilterValue = Primitive | Record<string, unknown> | unknown[];
+
+export function Filter(
+  fieldPath: string | FieldPath,
+  operator: FieldFilterOperator,
+  value: FilterValue | unknown,
+): _Filter {
+  return new _Filter(fieldPath, operator, value as FilterValue);
+}
+
+export class _Filter {
+  fieldPath?: string | FieldPath;
+  operator: FieldFilterOperator | FilterOperator;
+  value?: FilterValue;
+  queries?: _Filter[];
+
+  constructor(
+    fieldPath: string | FieldPath | null,
+    operator: FieldFilterOperator | FilterOperator | null,
+    value: FilterValue | null,
+    filterOperator?: FilterOperator,
+    queries?: _Filter[],
+  ) {
+    if (filterOperator !== undefined && [AND_QUERY, OR_QUERY].includes(filterOperator)) {
+      this.operator = filterOperator;
+      this.queries = queries;
+      return;
+    }
+
+    this.fieldPath = fieldPath ?? undefined;
+    this.operator = operator as FieldFilterOperator | FilterOperator;
+    // Preserve null for == / != (required for mapFieldQuery; do not coerce to undefined)
+    this.value = value as FilterValue | undefined;
+  }
+
+  _toMap(): FilterMap {
+    if ([AND_QUERY, OR_QUERY].includes(this.operator as FilterOperator)) {
+      return {
+        operator: this.operator,
+        queries: this.queries!.map(query => query._toMap()),
+      };
+    }
+
+    return {
+      fieldPath: this.fieldPath,
+      operator: this.operator,
+      value: this.value,
+    };
+  }
+}
+
+Filter.and = function and(...queries: _Filter[]): _Filter {
+  if (queries.length > 10 || queries.length < 1) {
+    throw new Error(`Expected 1-10 instances of Filter, but got ${queries.length} Filters`);
+  }
+
+  const validateFilters = queries.every(filter => filter instanceof _Filter);
+  if (!validateFilters) {
+    throw new Error('Expected every argument to be an instance of Filter');
+  }
+
+  return new _Filter(null, null, null, AND_QUERY, queries);
+};
+
+/** Serialized field filter or composite (AND/OR) for generateFilters output. */
+interface SerializedFieldFilter {
+  fieldPath: FieldPath | string[];
+  operator: string;
+  value: [number, unknown?] | null;
+}
+interface SerializedCompositeFilter {
+  operator: FilterOperator;
+  queries: SerializedFilterSpec[];
+}
+type SerializedFilterSpec = SerializedFieldFilter | SerializedCompositeFilter;
+
+function hasOrOperator(obj: _Filter): boolean {
+  return (
+    obj.operator === OR_QUERY ||
+    (Array.isArray(obj.queries) && obj.queries.some(query => hasOrOperator(query)))
+  );
+}
+
+Filter.or = function or(...queries: _Filter[]): _Filter {
+  if (queries.length > 10 || queries.length < 1) {
+    throw new Error(`Expected 1-10 instances of Filter, but got ${queries.length} Filters`);
+  }
+
+  const validateFilters = queries.every(filter => filter instanceof _Filter);
+  if (!validateFilters) {
+    throw new Error('Expected every argument to be an instance of Filter');
+  }
+
+  if (queries.some(hasOrOperator)) {
+    throw new Error('OR Filters with nested OR Filters are not supported');
+  }
+
+  return new _Filter(null, null, null, OR_QUERY, queries);
+};
+
+interface FilterMap {
+  fieldPath?: string | FieldPath;
+  operator: FieldFilterOperator | FilterOperator;
+  value?: FilterValue;
+  queries?: FilterMap[];
+}
+
+/** Modifiers object passed to generateFilters (e.g. QueryModifiers). */
+export interface FilterModifiersInternal {
+  isValidOperator(operator: string): boolean;
+  isEqualOperator(operator: string): boolean;
+  isNotEqualOperator(operator: string): boolean;
+  isInOperator(operator: string): boolean;
+}
+
+function mapFieldQuery(
+  filterMap: FilterMap,
+  modifiers: FilterModifiersInternal,
+): SerializedFilterSpec {
+  const { fieldPath, operator, value, queries } = filterMap;
+  if (operator === AND_QUERY || operator === OR_QUERY) {
+    return {
+      operator,
+      queries: (queries ?? []).map(q => mapFieldQuery(q, modifiers)),
+    };
+  }
+
+  let path: FieldPath | string;
+  if (isString(fieldPath)) {
+    try {
+      path = fromDotSeparatedString(fieldPath);
+    } catch (e) {
+      throw new Error(`first argument of Filter(*,_ , _) 'fieldPath' ${(e as Error).message}.`);
+    }
+  } else if (fieldPath !== undefined) {
+    path = fieldPath;
+  } else {
+    throw new Error("first argument of Filter(*,_ , _) 'fieldPath' is required.");
+  }
+
+  if (!modifiers.isValidOperator(operator)) {
+    throw new Error(
+      "second argument of Filter(*,_ , _) 'opStr' is invalid. Expected one of '==', '>', '>=', '<', '<=', '!=', 'array-contains', 'not-in', 'array-contains-any' or 'in'.",
+    );
+  }
+
+  if (isUndefined(value)) {
+    throw new Error("third argument of Filter(*,_ , _) 'value' argument expected.");
+  }
+
+  if (
+    isNull(value) &&
+    !modifiers.isEqualOperator(operator) &&
+    !modifiers.isNotEqualOperator(operator)
+  ) {
+    throw new Error(
+      "third argument of Filter(*,_ , _) 'value' is invalid. You can only perform equals comparisons on null",
+    );
+  }
+
+  if (modifiers.isInOperator(operator)) {
+    if (!isArray(value) || !value.length) {
+      throw new Error(
+        `third argument of Filter(*,_ , _) 'value' is invalid. A non-empty array is required for '${String(
+          operator,
+        )}' filters.`,
+      );
+    }
+
+    if (value.length > 10) {
+      throw new Error(
+        `third argument of Filter(*,_ , _) 'value' is invalid. '${String(
+          operator,
+        )}' filters support a maximum of 10 elements in the value array.`,
+      );
+    }
+  }
+
+  return {
+    fieldPath: path,
+    operator: OPERATORS[operator as FieldFilterOperator]!,
+    value: generateNativeData(value, true),
+  };
+}
+
+export function generateFilters(
+  filter: _Filter,
+  modifiers: FilterModifiersInternal,
+): { operator: string; queries: SerializedFilterSpec[] } {
+  const filterMap = filter._toMap();
+  const queries = (filterMap.queries ?? []).map(q => mapFieldQuery(q, modifiers));
+  return {
+    operator: filterMap.operator ?? '',
+    queries,
+  };
+}