@react-native-firebase/firestore 23.8.8 → 24.0.0

package/lib/FirestoreTimestamp.ts

@@ -0,0 +1,161 @@
+/*
+ * 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 { isDate, isNumber, isObject } from '@react-native-firebase/app/dist/module/common';
+
+// Earliest date supported by Firestore timestamps (0001-01-01T00:00:00Z).
+const MIN_SECONDS = -62135596800;
+
+export default class Timestamp {
+  static now(): Timestamp {
+    return Timestamp.fromMillis(Date.now());
+  }
+
+  static fromDate(date: Date): Timestamp {
+    if (!isDate(date)) {
+      throw new Error(
+        "firebase.firestore.Timestamp.fromDate(*) 'date' expected a valid Date object.",
+      );
+    }
+
+    return Timestamp.fromMillis(date.getTime());
+  }
+
+  static fromMillis(milliseconds: number): Timestamp {
+    const seconds = Math.floor(milliseconds / 1000);
+    const nanoseconds = (milliseconds - seconds * 1000) * 1e6;
+    return new Timestamp(seconds, nanoseconds);
+  }
+
+  _seconds: number;
+  _nanoseconds: number;
+
+  constructor(seconds: number, nanoseconds: number) {
+    if (!isNumber(seconds)) {
+      throw new Error("firebase.firestore.Timestamp 'seconds' expected a number value.");
+    }
+
+    if (!isNumber(nanoseconds)) {
+      throw new Error("firebase.firestore.Timestamp 'nanoseconds' expected a number value.");
+    }
+
+    if (nanoseconds < 0) {
+      throw new Error(`firebase.firestore.Timestamp 'nanoseconds' out of range: ${nanoseconds}`);
+    }
+
+    if (nanoseconds >= 1e9) {
+      throw new Error(`firebase.firestore.Timestamp 'nanoseconds' out of range: ${nanoseconds}`);
+    }
+
+    if (seconds < MIN_SECONDS) {
+      throw new Error(`firebase.firestore.Timestamp 'seconds' out of range: ${seconds}`);
+    }
+
+    if (seconds >= 253402300800) {
+      throw new Error(`firebase.firestore.Timestamp 'seconds' out of range: ${seconds}`);
+    }
+
+    this._seconds = seconds;
+    this._nanoseconds = nanoseconds;
+  }
+
+  get seconds(): number {
+    return this._seconds;
+  }
+
+  get nanoseconds(): number {
+    return this._nanoseconds;
+  }
+
+  isEqual(other: Timestamp): boolean {
+    if (!(other instanceof Timestamp)) {
+      throw Error(
+        "firebase.firestore.Timestamp.isEqual(*) 'other' expected an instance of Timestamp.",
+      );
+    }
+
+    return other.seconds === this._seconds && other.nanoseconds === this._nanoseconds;
+  }
+
+  toDate(): Date {
+    return new Date(this.toMillis());
+  }
+
+  toMillis(): number {
+    return this._seconds * 1000 + this._nanoseconds / 1e6;
+  }
+
+  _compareTo(other: Timestamp): number {
+    if (this._seconds === other._seconds) {
+      if (this._nanoseconds < other._nanoseconds) return -1;
+      if (this._nanoseconds > other._nanoseconds) return 1;
+      return 0;
+    }
+    return this._seconds < other._seconds ? -1 : 1;
+  }
+
+  toString(): string {
+    return `Timestamp(seconds=${this.seconds}, nanoseconds=${this.nanoseconds})`;
+  }
+
+  static _jsonSchemaVersion: string = 'firestore/timestamp/1.0';
+  static _jsonSchema = {
+    type: Timestamp._jsonSchemaVersion,
+    seconds: 'number',
+    nanoseconds: 'number',
+  };
+
+  toJSON(): { seconds: number; nanoseconds: number; type: string } {
+    return {
+      type: Timestamp._jsonSchemaVersion,
+      seconds: this.seconds,
+      nanoseconds: this.nanoseconds,
+    };
+  }
+
+  static fromJSON(json: object): Timestamp {
+    if (
+      isObject(json) &&
+      (json as { type?: unknown }).type === Timestamp._jsonSchemaVersion &&
+      typeof (json as { seconds?: unknown }).seconds === 'number' &&
+      typeof (json as { nanoseconds?: unknown }).nanoseconds === 'number'
+    ) {
+      return new Timestamp(
+        (json as { seconds: number }).seconds,
+        (json as { nanoseconds: number }).nanoseconds,
+      );
+    }
+
+    throw new Error('Unexpected error creating Timestamp from JSON.');
+  }
+  /**
+   * Converts this object to a primitive string, which allows Timestamp objects to be compared
+   * using the `>`, `<=`, `>=` and `>` operators.
+   */
+  valueOf(): string {
+    // This method returns a string of the form <seconds>.<nanoseconds> where <seconds> is
+    // translated to have a non-negative value and both <seconds> and <nanoseconds> are left-padded
+    // with zeroes to be a consistent length. Strings with this format then have a lexiographical
+    // ordering that matches the expected ordering. The <seconds> translation is done to avoid
+    // having a leading negative sign (i.e. a leading '-' character) in its string representation,
+    // which would affect its lexiographical ordering.
+    const adjustedSeconds = this.seconds - MIN_SECONDS;
+    const formattedSeconds = String(adjustedSeconds).padStart(12, '0');
+    const formattedNanoseconds = String(this.nanoseconds).padStart(9, '0');
+    return `${formattedSeconds}.${formattedNanoseconds}`;
+  }
+}

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

@@ -16,24 +16,50 @@
  */
 
 import { isObject, createDeprecationProxy } from '@react-native-firebase/app/dist/module/common';
-import FirestoreDocumentReference from './FirestoreDocumentReference';
-import FirestoreDocumentSnapshot from './FirestoreDocumentSnapshot';
-import { parseSetOptions, parseUpdateArgs } from './utils';
+import DocumentReference from './FirestoreDocumentReference';
+import DocumentSnapshot from './FirestoreDocumentSnapshot';
+import type { DocumentSnapshotNativeData } from './FirestoreDocumentSnapshot';
+import { parseSetOptions, parseUpdateArgs, applyFirestoreDataConverter } from './utils';
 import { buildNativeMap } from './utils/serialize';
+import type { FirestoreInternal } from './types/internal';
+import type { SetOptions } from './types/firestore';
+
+export interface TransactionMeta {
+  id: number;
+  /** Receives the Transaction instance (this module's default export). */
+  updateFunction: (transaction: Transaction) => Promise<unknown>;
+  stack?: string;
+  resolve?: (result: unknown) => void;
+  reject?: (error: unknown) => void;
+}
+
+export interface TransactionCommand {
+  type: 'SET' | 'UPDATE' | 'DELETE';
+  path: string;
+  data?: Record<string, unknown>;
+  options?: Record<string, unknown>;
+}
 
-export default class FirestoreTransaction {
-  constructor(firestore, meta) {
+export default class Transaction {
+  _firestore: FirestoreInternal;
+  _meta: TransactionMeta;
+  _calledGetCount: number;
+  _commandBuffer: TransactionCommand[];
+  _pendingResult: unknown;
+
+  constructor(firestore: FirestoreInternal, meta: TransactionMeta) {
     this._firestore = firestore;
     this._meta = meta;
+    this._calledGetCount = 0;
+    this._commandBuffer = [];
+    this._pendingResult = undefined;
   }
 
   /**
    * Clears the command buffer and any pending result in prep for
    * the next transaction iteration attempt.
-   *
-   * @private
    */
-  _prepare() {
+  _prepare(): void {
     this._calledGetCount = 0;
     this._commandBuffer = [];
     this._pendingResult = undefined;
@@ -42,8 +68,8 @@ export default class FirestoreTransaction {
   /**
    * Reads the document referenced by the provided DocumentReference.
    */
-  get(documentRef) {
-    if (!(documentRef instanceof FirestoreDocumentReference)) {
+  get(documentRef: DocumentReference): Promise<DocumentSnapshot> {
+    if (!(documentRef instanceof DocumentReference)) {
       throw new Error(
         "firebase.firestore().runTransaction() Transaction.get(*) 'documentRef' expected a DocumentReference.",
       );
@@ -52,59 +78,70 @@ export default class FirestoreTransaction {
     this._calledGetCount++;
     return this._firestore.native
       .transactionGetDocument(this._meta.id, documentRef.path)
-      .then(data => createDeprecationProxy(new FirestoreDocumentSnapshot(this._firestore, data)));
+      .then((data: unknown) =>
+        createDeprecationProxy(
+          new DocumentSnapshot(this._firestore, data as DocumentSnapshotNativeData, null),
+        ),
+      );
   }
 
   /**
    * Writes to the document referred to by the provided DocumentReference.
-   * If the document does not exist yet, it will be created. If you pass options,
-   * the provided data can be merged into the existing document.
    */
-  set(documentRef, data, options) {
-    if (!(documentRef instanceof FirestoreDocumentReference)) {
+  set(documentRef: DocumentReference, data: Record<string, unknown>, options?: SetOptions): this {
+    if (!(documentRef instanceof DocumentReference)) {
       throw new Error(
         "firebase.firestore().runTransaction() Transaction.set(*) 'documentRef' expected a DocumentReference.",
       );
     }
 
-    if (!isObject(data)) {
+    let setOptions: Record<string, unknown>;
+    try {
+      setOptions = parseSetOptions(options);
+    } catch (e) {
       throw new Error(
-        "firebase.firestore().runTransaction() Transaction.set(_, *) 'data' must be an object..",
+        `firebase.firestore().runTransaction() Transaction.set(_, _, *) ${(e as Error).message}.`,
       );
     }
 
-    let setOptions;
+    let converted: Record<string, unknown> | unknown = data;
     try {
-      setOptions = parseSetOptions(options);
+      converted = applyFirestoreDataConverter(data, documentRef.converter, setOptions);
     } catch (e) {
       throw new Error(
-        `firebase.firestore().runTransaction() Transaction.set(_, _, *) ${e.message}.`,
+        `firebase.firestore().runTransaction() Transaction.set(_, *) 'withConverter.toFirestore' threw an error: ${(e as Error).message}.`,
+      );
+    }
+
+    if (!isObject(converted)) {
+      throw new Error(
+        "firebase.firestore().runTransaction() Transaction.set(_, *) 'data' must be an object..",
       );
     }
 
     this._commandBuffer.push({
       type: 'SET',
       path: documentRef.path,
-      data: buildNativeMap(data, this._firestore._settings.ignoreUndefinedProperties),
+      data: buildNativeMap(converted, this._firestore._settings.ignoreUndefinedProperties),
       options: setOptions,
     });
 
     return this;
   }
 
-  update(documentRef, ...args) {
-    if (!(documentRef instanceof FirestoreDocumentReference)) {
+  update(documentRef: DocumentReference, ...args: unknown[]): this {
+    if (!(documentRef instanceof DocumentReference)) {
       throw new Error(
         "firebase.firestore().runTransaction() Transaction.update(*) 'documentRef' expected a DocumentReference.",
       );
     }
 
-    let data;
+    let data: Record<string, unknown>;
     try {
       data = parseUpdateArgs(args);
     } catch (e) {
       throw new Error(
-        `firebase.firestore().runTransaction() Transaction.update(_, *) ${e.message}`,
+        `firebase.firestore().runTransaction() Transaction.update(_, *) ${(e as Error).message}`,
       );
     }
 
@@ -117,8 +154,8 @@ export default class FirestoreTransaction {
     return this;
   }
 
-  delete(documentRef) {
-    if (!(documentRef instanceof FirestoreDocumentReference)) {
+  delete(documentRef: DocumentReference): this {
+    if (!(documentRef instanceof DocumentReference)) {
       throw new Error(
         "firebase.firestore().runTransaction() Transaction.delete(*) 'documentRef' expected a DocumentReference.",
       );

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

@@ -16,19 +16,33 @@
  */
 
 import NativeError from '@react-native-firebase/app/dist/module/internal/NativeFirebaseError';
-import FirestoreTransaction from './FirestoreTransaction';
+import Transaction, { type TransactionMeta } from './FirestoreTransaction';
+import type { FirestoreInternal } from './types/internal';
 
 let transactionId = 0;
 
-/**
- * Uses the push id generator to create a transaction id
- * @returns {number}
- * @private
- */
-const generateTransactionId = () => transactionId++;
+const generateTransactionId = (): number => transactionId++;
+
+export interface TransactionPendingEntry {
+  meta: TransactionMeta;
+  transaction: Transaction;
+}
+
+export interface TransactionEventBody {
+  type?: 'update' | 'error' | 'complete';
+  error?: unknown;
+}
+
+export interface TransactionEvent {
+  body: TransactionEventBody;
+  listenerId?: number;
+}
 
 export default class FirestoreTransactionHandler {
-  constructor(firestore) {
+  _firestore: FirestoreInternal;
+  _pending: Record<number, TransactionPendingEntry>;
+
+  constructor(firestore: FirestoreInternal) {
     this._firestore = firestore;
     this._pending = {};
     this._firestore.emitter.addListener(
@@ -37,7 +51,7 @@ export default class FirestoreTransactionHandler {
     );
   }
 
-  _onTransactionEvent(event) {
+  _onTransactionEvent(event: TransactionEvent): void {
     switch (event.body.type) {
       case 'update':
         this._handleUpdate(event);
@@ -51,29 +65,29 @@ export default class FirestoreTransactionHandler {
     }
   }
 
-  async _handleUpdate(event) {
-    const { listenerId: id } = event;
+  async _handleUpdate(event: TransactionEvent): Promise<void> {
+    const id = event.listenerId;
 
-    // abort if no longer exists js side
-    if (!this._pending[id]) {
-      return this._remove(id);
+    if (id === undefined || !this._pending[id]) {
+      if (id !== undefined) {
+        this._remove(id);
+      }
+      return;
     }
 
     const { meta, transaction } = this._pending[id];
     const { updateFunction, reject } = meta;
 
-    // clear any saved state from previous transaction runs
     transaction._prepare();
 
-    let finalError;
-    let updateFailed;
-    let pendingResult;
+    let finalError: unknown;
+    let updateFailed = false;
+    let pendingResult: unknown;
 
     try {
       const possiblePromise = updateFunction(transaction);
 
-      // validate user has returned a promise in their update function
-      if (!possiblePromise || !possiblePromise.then) {
+      if (!possiblePromise || typeof (possiblePromise as Promise<unknown>)?.then !== 'function') {
         throw new Error(
           "firebase.firestore().runTransaction(*) 'updateFunction' must return a Promise.",
         );
@@ -81,39 +95,25 @@ export default class FirestoreTransactionHandler {
 
       pendingResult = await possiblePromise;
     } catch (exception) {
-      // exception can still be falsey if user `Promise.reject();` 's with no args
-      // so we track the exception with a updateFailed boolean to ensure no fall-through
       updateFailed = true;
       finalError = exception;
     }
 
-    // reject the final promise and remove from native
-    // update is failed when either the users updateFunction
-    // throws an error or rejects a promise
     if (updateFailed || finalError) {
-      return reject(finalError);
+      reject?.(finalError);
+      return;
     }
 
-    // capture the resolved result as we'll need this
-    // to resolve the runTransaction() promise when
-    // native emits that the transaction is final
     transaction._pendingResult = pendingResult;
 
-    // send the buffered update/set/delete commands for native to process
     return this._firestore.native.transactionApplyBuffer(id, transaction._commandBuffer);
   }
 
-  /**
-   * Reject the promise with a native error event
-   *
-   * @param event
-   * @private
-   */
-  _handleError(event) {
-    const { listenerId: id, body } = event;
-    const { error } = body;
-
-    if (!this._pending[id]) {
+  _handleError(event: TransactionEvent): void {
+    const id = event.listenerId;
+    const { error } = event.body;
+
+    if (id === undefined || !this._pending[id]) {
       return;
     }
 
@@ -121,74 +121,53 @@ export default class FirestoreTransactionHandler {
 
     if (meta && error) {
       const errorAndStack = NativeError.fromEvent(error, 'firestore', meta.stack);
-      meta.reject(errorAndStack);
+      meta.reject?.(errorAndStack);
     }
   }
 
-  /**
-   * Once the transaction has completed on native, resolve the promise with any
-   * pending results
-   *
-   * @param event
-   * @private
-   */
-  _handleComplete(event) {
-    const { listenerId: id } = event;
-
-    if (!this._pending[id]) {
+  _handleComplete(event: TransactionEvent): void {
+    const id = event.listenerId;
+
+    if (id === undefined || !this._pending[id]) {
       return;
     }
 
     const { meta, transaction } = this._pending[id];
     if (meta) {
-      meta.resolve(transaction._pendingResult);
+      meta.resolve?.(transaction._pendingResult);
     }
   }
 
-  /**
-   * Internally adds a transaction execution function to the queue
-   *
-   * @param updateFunction
-   * @returns {Promise<any>}
-   * @private
-   */
-  _add(updateFunction) {
+  _add(updateFunction: (transaction: Transaction) => Promise<unknown>): Promise<unknown> {
     const id = generateTransactionId();
 
-    const meta = {
+    const meta: TransactionMeta = {
       id,
       updateFunction,
-      stack: new Error().stack.split('\n').slice(2).join('\n'),
+      stack: new Error().stack?.split('\n').slice(2).join('\n'),
     };
 
     this._pending[id] = {
       meta,
-      transaction: new FirestoreTransaction(this._firestore, meta),
+      transaction: new Transaction(this._firestore, meta),
     };
 
     return new Promise((resolve, reject) => {
       this._firestore.native.transactionBegin(id);
 
-      meta.resolve = result => {
+      meta.resolve = (result: unknown) => {
         this._remove(id);
         resolve(result);
       };
 
-      meta.reject = error => {
+      meta.reject = (error: unknown) => {
         this._remove(id);
         reject(error);
       };
     });
   }
 
-  /**
-   * Internally removes the transaction once it has resolved
-   * or rejected
-   *
-   * @param id
-   * @private
-   */
-  _remove(id) {
+  _remove(id: number): void {
     this._firestore.native.transactionDispose(id);
     delete this._pending[id];
   }

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

@@ -15,10 +15,14 @@
  *
  */
 
-import { isArray, isNumber } from '@react-native-firebase/app/dist/module/common';
+import { isArray, isNumber, isObject } from '@react-native-firebase/app/dist/module/common';
 
-export default class FirestoreVectorValue {
-  constructor(values) {
+type FirestoreVectorJson = { vectorValues: number[]; type?: string };
+
+export default class VectorValue {
+  _values: number[];
+
+  constructor(values?: number[]) {
     if (values === undefined) {
       this._values = [];
       return;
@@ -31,25 +35,43 @@ export default class FirestoreVectorValue {
     }
 
     for (let i = 0; i < values.length; i++) {
-      const v = values[i];
-      if (!isNumber(v)) {
+      const value = values[i];
+      if (!isNumber(value)) {
         throw new Error(
           `firebase.firestore.VectorValue(values?) 'values[${i}]' expected a number value.`,
         );
       }
     }
 
-    // Store a shallow copy to ensure immutability semantics for the input array
     this._values = values.slice();
   }
 
-  static fromJSON(json) {
-    parsedVector = JSON.parse(json);
-    return new FirestoreVectorValue(parsedVector.vectorValues);
+  static _jsonSchemaVersion: string = 'firestore/vectorValue/1.0';
+  static _jsonSchema = {
+    type: VectorValue._jsonSchemaVersion,
+    vectorValues: 'object',
+  };
+
+  static fromJSON(json: object): VectorValue {
+    const parsedVector = isObject(json) ? (json as FirestoreVectorJson & { type?: unknown }) : null;
+    if (
+      parsedVector &&
+      (parsedVector.type === undefined || parsedVector.type === VectorValue._jsonSchemaVersion) &&
+      Array.isArray(parsedVector.vectorValues) &&
+      parsedVector.vectorValues.every(element => typeof element === 'number')
+    ) {
+      return new VectorValue(parsedVector.vectorValues);
+    }
+
+    if (parsedVector && parsedVector.type === VectorValue._jsonSchemaVersion) {
+      throw new Error("Expected 'vectorValues' field to be a number array");
+    }
+
+    throw new Error('Unexpected error creating Timestamp from JSON.');
   }
 
-  isEqual(other) {
-    if (!(other instanceof FirestoreVectorValue)) {
+  isEqual(other: VectorValue): boolean {
+    if (!(other instanceof VectorValue)) {
       throw new Error(
         "firebase.firestore.VectorValue.isEqual(*) 'other' expected a VectorValue instance.",
       );
@@ -59,17 +81,16 @@ export default class FirestoreVectorValue {
     const b = other._values;
     if (a.length !== b.length) return false;
     for (let i = 0; i < a.length; i++) {
-      // Use strict equality; Firestore numbers allow NaN/Infinity – equality semantics match JS
       if (a[i] !== b[i]) return false;
     }
     return true;
   }
 
-  toArray() {
+  toArray(): number[] {
     return this._values.slice();
   }
 
-  toJSON() {
-    return { vectorValues: this._values.slice() };
+  toJSON(): { vectorValues: number[]; type: string } {
+    return { type: VectorValue._jsonSchemaVersion, vectorValues: this._values.slice() };
   }
 }