firestore-node-mock 0.0.1

package/mocks/helpers/buildDocFromHash.js

@@ -0,0 +1,73 @@
+import * as timestamp from '../timestamp.js';
+import pkg from 'lodash';
+const { merge } = pkg;
+
+export default function buildDocFromHash(hash = {}, id = 'abc123', selectFields = undefined) {
+  const exists = !!hash || false;
+  return {
+    createTime: (hash && hash._createTime) || timestamp.Timestamp.now(),
+    exists,
+    id: (hash && hash.id) || id,
+    readTime: hash && hash._readTime,
+    ref: hash && hash._ref,
+    metadata: {
+      hasPendingWrites: 'Server',
+    },
+    updateTime: hash && hash._updateTime,
+    data() {
+      if (!exists) {
+        // From Firestore docs: "Returns 'undefined' if the document doesn't exist."
+        // See https://firebase.google.com/docs/reference/js/firestore_.documentsnapshot#documentsnapshotdata
+        return undefined;
+      }
+      let copy = { ...hash };
+      if (!hash._ref.parent.firestore.options.includeIdsInData) {
+        delete copy.id;
+      }
+      delete copy._collections;
+      delete copy._createTime;
+      delete copy._readTime;
+      delete copy._ref;
+      delete copy._updateTime;
+
+      if (selectFields !== undefined) {
+        copy = selectFields.reduce((acc, field) => {
+          const path = field.split('.');
+          return merge(acc, buildDocFromPath(copy, path));
+        }, {});
+      }
+
+      return copy;
+    },
+    get(fieldPath) {
+      // The field path can be compound: from the firestore docs
+      //  fieldPath The path (e.g. 'foo' or 'foo.bar') to a specific field.
+      const parts = fieldPath.split('.');
+      const data = this.data();
+      return parts.reduce((acc, part, index) => {
+        const value = acc[part];
+        // if no key is found
+        if (value === undefined) {
+          // return null if we are on the last item in parts
+          // otherwise, return an empty object, so we can continue to iterate
+          return parts.length - 1 === index ? null : {};
+        }
+
+        // if there is a value, return it
+        return value;
+      }, data);
+    },
+  };
+};
+
+function buildDocFromPath(data, path) {
+  if (data === undefined || data === null) {
+    return {};
+  }
+
+  const [root, ...subPath] = path;
+  const rootData = data[root];
+  return {
+    [root]: subPath.length ? buildDocFromPath(rootData, subPath) : rootData
+  };
+}

package/mocks/helpers/buildQuerySnapShot.d.ts

@@ -0,0 +1,29 @@
+import type { MockedDocument, DocumentHash } from './buildDocFromHash.js';
+
+export type Comparator = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'not-in' | 'array-contains-any';
+
+export interface QueryFilter {
+  key: string;
+  comp: Comparator;
+  value: string;
+}
+
+export interface MockedQuerySnapshot<Doc = MockedDocument> {
+  empty: boolean;
+  size: number;
+  docs: Array<Doc>;
+  forEach(callbackfn: (value: Doc, index: number, array: Array<Doc>) => void): void;
+  docChanges(): Array<never>;
+}
+
+/**
+ * Builds a query result from the given array of record objects.
+ *
+ * @param requestedRecords
+ * @param filters
+ */
+export default function buildQuerySnapShot(
+  requestedRecords: Array<DocumentHash>,
+  filters?: Array<QueryFilter>,
+  selectFields?: string[],
+): MockedQuerySnapshot;

package/mocks/helpers/buildQuerySnapShot.js

@@ -0,0 +1,306 @@
+import buildDocFromHash from './buildDocFromHash.js';
+
+export default function buildQuerySnapShot(requestedRecords, filters, selectFields) {
+  const definiteRecords = requestedRecords.filter(rec => !!rec);
+  const results = _filteredDocuments(definiteRecords, filters);
+  const docs = results.map(doc => buildDocFromHash(doc, 'abc123', selectFields));
+
+  return {
+    empty: results.length < 1,
+    size: results.length,
+    docs,
+    forEach(callback) {
+      docs.forEach(callback);
+    },
+    docChanges() {
+      return [];
+    },
+  };
+};
+
+/**
+ * @typedef DocumentHash
+ * @type {import('./buildDocFromHash.js').DocumentHash}
+ */
+
+/**
+ * @typedef Comparator
+ * @type {import('./buildQuerySnapShot.js').Comparator}
+ */
+
+/**
+ * Applies query filters to an array of mock document data.
+ *
+ * @param {Array<DocumentHash>} records The array of records to filter.
+ * @param {Array<{ key: string; comp: Comparator; value: unknown }>=} filters The filters to apply.
+ * If no filters are provided, then the records array is returned as-is.
+ *
+ * @returns {Array<import('./buildDocFromHash.js').DocumentHash>} The filtered documents.
+ */
+function _filteredDocuments(records, filters) {
+  if (!filters || !Array.isArray(filters) || filters.length === 0) {
+    return records;
+  }
+
+  filters.forEach(({ key, comp, value }) => {
+    // https://firebase.google.com/docs/reference/js/firebase.firestore#wherefilterop
+    // Convert values to string to make Array comparisons work
+    // See https://jsbin.com/bibawaf/edit?js,console
+
+    switch (comp) {
+      // https://firebase.google.com/docs/firestore/query-data/queries#query_operators
+      case '<':
+        records = _recordsLessThanValue(records, key, value);
+        break;
+
+      case '<=':
+        records = _recordsLessThanOrEqualToValue(records, key, value);
+        break;
+
+      case '==':
+        records = _recordsEqualToValue(records, key, value);
+        break;
+
+      case '!=':
+        records = _recordsNotEqualToValue(records, key, value);
+        break;
+
+      case '>=':
+        records = _recordsGreaterThanOrEqualToValue(records, key, value);
+        break;
+
+      case '>':
+        records = _recordsGreaterThanValue(records, key, value);
+        break;
+
+      case 'array-contains':
+        records = _recordsArrayContainsValue(records, key, value);
+        break;
+
+      case 'in':
+        records = _recordsWithValueInList(records, key, value);
+        break;
+
+      case 'not-in':
+        records = _recordsWithValueNotInList(records, key, value);
+        break;
+
+      case 'array-contains-any':
+        records = _recordsWithOneOfValues(records, key, value);
+        break;
+    }
+  });
+
+  return records;
+}
+
+function _recordsWithKey(records, key) {
+  return records.filter(record => record && getValueByPath(record, key) !== undefined);
+}
+
+function _recordsWithNonNullKey(records, key) {
+  return records.filter(
+    record =>
+      record && getValueByPath(record, key) !== undefined && getValueByPath(record, key) !== null,
+  );
+}
+
+function _shouldCompareNumerically(a, b) {
+  return typeof a === 'number' && typeof b === 'number';
+}
+
+function _shouldCompareTimestamp(a, b) {
+  //We check whether toMillis method exists to support both Timestamp mock and Firestore Timestamp object
+  //B is expected to be Date, not Timestamp, just like Firestore does
+  return (
+    typeof a === 'object' && a !== null && typeof a.toMillis === 'function' && b instanceof Date
+  );
+}
+
+/**
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsLessThanValue(records, key, value) {
+  return _recordsWithNonNullKey(records, key).filter(record => {
+    const recordValue = getValueByPath(record, key);
+    if (_shouldCompareNumerically(recordValue, value)) {
+      return recordValue < value;
+    }
+    if (_shouldCompareTimestamp(recordValue, value)) {
+      return recordValue.toMillis() < value;
+    }
+    return String(recordValue) < String(value);
+  });
+}
+
+/**
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsLessThanOrEqualToValue(records, key, value) {
+  return _recordsWithNonNullKey(records, key).filter(record => {
+    const recordValue = getValueByPath(record, key);
+    if (_shouldCompareNumerically(recordValue, value)) {
+      return recordValue <= value;
+    }
+    if (_shouldCompareTimestamp(recordValue, value)) {
+      return recordValue.toMillis() <= value;
+    }
+    return String(recordValue) <= String(value);
+  });
+}
+
+/**
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsEqualToValue(records, key, value) {
+  return _recordsWithKey(records, key).filter(record => {
+    const recordValue = getValueByPath(record, key);
+    if (_shouldCompareTimestamp(recordValue, value)) {
+      //NOTE: for equality, we must compare numbers!
+      return recordValue.toMillis() === value.getTime();
+    }
+    return String(recordValue) === String(value);
+  });
+}
+
+/**
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsNotEqualToValue(records, key, value) {
+  return _recordsWithKey(records, key).filter(record => {
+    const recordValue = getValueByPath(record, key);
+    if (_shouldCompareTimestamp(recordValue, value)) {
+      //NOTE: for equality, we must compare numbers!
+      return recordValue.toMillis() !== value.getTime();
+    }
+    return String(recordValue) !== String(value);
+  });
+}
+
+/**
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsGreaterThanOrEqualToValue(records, key, value) {
+  return _recordsWithNonNullKey(records, key).filter(record => {
+    const recordValue = getValueByPath(record, key);
+    if (_shouldCompareNumerically(recordValue, value)) {
+      return recordValue >= value;
+    }
+    if (_shouldCompareTimestamp(recordValue, value)) {
+      return recordValue.toMillis() >= value;
+    }
+    return String(recordValue) >= String(value);
+  });
+}
+
+/**
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsGreaterThanValue(records, key, value) {
+  return _recordsWithNonNullKey(records, key).filter(record => {
+    const recordValue = getValueByPath(record, key);
+    if (_shouldCompareNumerically(recordValue, value)) {
+      return recordValue > value;
+    }
+    if (_shouldCompareTimestamp(recordValue, value)) {
+      return recordValue.toMillis() > value;
+    }
+    return String(recordValue) > String(value);
+  });
+}
+
+/**
+ * @see https://firebase.google.com/docs/firestore/query-data/queries#array_membership
+ *
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsArrayContainsValue(records, key, value) {
+  return records.filter(
+    record =>
+      record &&
+      getValueByPath(record, key) &&
+      Array.isArray(getValueByPath(record, key)) &&
+      getValueByPath(record, key).includes(value),
+  );
+}
+
+/**
+ * @see https://firebase.google.com/docs/firestore/query-data/queries#in_not-in_and_array-contains-any
+ *
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsWithValueInList(records, key, value) {
+  // TODO: Throw an error when a value is passed that contains more than 10 values
+  return records.filter(record => {
+    if (!record || getValueByPath(record, key) === undefined) {
+      return false;
+    }
+    return value && Array.isArray(value) && value.includes(getValueByPath(record, key));
+  });
+}
+
+/**
+ * @see https://firebase.google.com/docs/firestore/query-data/queries#not-in
+ *
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsWithValueNotInList(records, key, value) {
+  // TODO: Throw an error when a value is passed that contains more than 10 values
+  return _recordsWithKey(records, key).filter(
+    record => value && Array.isArray(value) && !value.includes(getValueByPath(record, key)),
+  );
+}
+
+/**
+ * @see https://firebase.google.com/docs/firestore/query-data/queries#in_not-in_and_array-contains-any
+ *
+ * @param {Array<DocumentHash>} records
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Array<DocumentHash>}
+ */
+function _recordsWithOneOfValues(records, key, value) {
+  // TODO: Throw an error when a value is passed that contains more than 10 values
+  return records.filter(
+    record =>
+      record &&
+      getValueByPath(record, key) &&
+      Array.isArray(getValueByPath(record, key)) &&
+      value &&
+      Array.isArray(value) &&
+      getValueByPath(record, key).some(v => value.includes(v)),
+  );
+}
+
+function getValueByPath(record, path) {
+  const keys = path.split('.');
+  return keys.reduce((nestedObject = {}, key) => nestedObject[key], record);
+}
+

package/mocks/helpers/defaultMockOptions.d.ts

@@ -0,0 +1,3 @@
+export const includeIdsInData: boolean;
+export const mutable: boolean;
+export const simulateQueryFilters: boolean;

package/mocks/helpers/defaultMockOptions.js

@@ -0,0 +1,5 @@
+export default {
+  includeIdsInData: false,
+  mutable: false,
+  simulateQueryFilters: false,
+};

package/mocks/path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @private
+ * @class
+ */
+declare abstract class Path<T> {
+  protected readonly segments: string[];
+  /**
+   * @private
+   * @hideconstructor
+   * @param segments
+   */
+  constructor(segments: string[]);
+  compareTo(other: Path<T>): number;
+  toArray(): string[];
+  isEqual(other: Path<T>): boolean;
+}
+
+/**
+ * @class
+ */
+export declare class FieldPath extends Path<FieldPath> implements FieldPath {
+  private static _DOCUMENT_ID;
+  constructor(...segments: string[]);
+  static documentId(): FieldPath;
+  isEqual(other: FieldPath): boolean;
+}

package/mocks/path.js

@@ -0,0 +1,39 @@
+export class Path {
+  constructor(segments) {
+    this.segments = segments;
+  }
+  compareTo(other) {
+    const len = Math.min(this.segments.length, other.segments.length);
+    for (let i = 0; i < len; i++) {
+      if (this.segments[i] < other.segments[i]) {
+        return -1;
+      }
+      if (this.segments[i] > other.segments[i]) {
+        return 1;
+      }
+    }
+    if (this.segments.length < other.segments.length) {
+      return -1;
+    }
+    if (this.segments.length > other.segments.length) {
+      return 1;
+    }
+    return 0;
+  }
+  isEqual(other) {
+    return this === other || this.compareTo(other) === 0;
+  }
+}
+
+export class FieldPath extends Path {
+  constructor(...segments) {
+    super(segments);
+  }
+  static documentId() {
+    return FieldPath._DOCUMENT_ID;
+  }
+  isEqual(other) {
+    return super.isEqual(other);
+  }
+}
+FieldPath._DOCUMENT_ID = new FieldPath('__name__');

package/mocks/query.d.ts

@@ -0,0 +1,32 @@
+import { Mock } from 'node:test';
+import type { FakeFirestore } from './firestore.js';
+import type { MockedQuerySnapshot } from './helpers/buildQuerySnapShot.js';
+
+export class Query {
+  constructor(collectionName: string, firestore: typeof FakeFirestore);
+
+  get(): Promise<MockedQuerySnapshot>;
+  select(): Query;
+  where(): Query;
+  offset(): Query;
+  limit(): Query;
+  orderBy(): Query;
+  startAfter(): Query;
+  startAt(): Query;
+  withConverter(): Query;
+  onSnapshot(): () => void;
+}
+
+export const mocks: {
+  mockGet: Mock<any>,
+  mockSelect: Mock<any>,
+  mockWhere: Mock<any>,
+  mockLimit: Mock<any>,
+  mockOrderBy: Mock<any>,
+  mockOffset: Mock<any>,
+  mockStartAfter: Mock<any>,
+  mockStartAt: Mock<any>,
+  mockQueryOnSnapshot: Mock<any>,
+  mockQueryOnSnapshotUnsubscribe: Mock<any>,
+  mockWithConverter: Mock<any>,
+};

package/mocks/query.js

@@ -0,0 +1,162 @@
+import { mock } from 'node:test';
+import buildQuerySnapShot from './helpers/buildQuerySnapShot.js';
+
+export const mockGet = mock.fn();
+export const mockSelect = mock.fn();
+export const mockWhere = mock.fn();
+export const mockLimit = mock.fn();
+export const mockOrderBy = mock.fn();
+export const mockOffset = mock.fn();
+export const mockStartAfter = mock.fn();
+export const mockStartAt = mock.fn();
+export const mockQueryOnSnapshot = mock.fn();
+export const mockQueryOnSnapshotUnsubscribe = mock.fn();
+export const mockWithConverter = mock.fn();
+
+export class Query {
+  constructor(collectionName, firestore, isGroupQuery = false) {
+    this.collectionName = collectionName;
+    this.firestore = firestore;
+    this.filters = [];
+    this.selectFields = undefined;
+    this.isGroupQuery = isGroupQuery;
+  }
+
+  get() {
+    mockGet(...arguments);
+    return Promise.resolve(this._get());
+  }
+
+  _get() {
+    // Simulate collectionGroup query
+
+    // Get Firestore collections whose name match `this.collectionName`; return their documents
+    const requestedRecords = [];
+
+    const queue = [
+      {
+        lastParent: '',
+        collections: this.firestore.database,
+      },
+    ];
+
+    while (queue.length > 0) {
+      // Get a collection
+      const { lastParent, collections } = queue.shift();
+
+      Object.entries(collections).forEach(([collectionPath, docs]) => {
+        const prefix = lastParent ? `${lastParent}/` : '';
+
+        const newLastParent = `${prefix}${collectionPath}`;
+        const lastPathComponent = collectionPath.split('/').pop();
+
+        // If this is a matching collection, grep its documents
+        if (lastPathComponent === this.collectionName) {
+          const docHashes = docs.map(doc => {
+            // Fetch the document from the mock db
+            const path = `${newLastParent}/${doc.id}`;
+            return {
+              ...doc,
+              _ref: this.firestore._doc(path),
+            };
+          });
+          requestedRecords.push(...docHashes);
+        }
+
+        // Enqueue adjacent collections for next run
+        docs.forEach(doc => {
+          if (doc._collections) {
+            queue.push({
+              lastParent: `${prefix}${collectionPath}/${doc.id}`,
+              collections: doc._collections,
+            });
+          }
+        });
+      });
+    }
+
+    // Return the requested documents
+    const isFilteringEnabled = this.firestore.options.simulateQueryFilters;
+    return buildQuerySnapShot(
+      requestedRecords,
+      isFilteringEnabled ? this.filters : undefined,
+      this.selectFields,
+    );
+  }
+
+  select(...fieldPaths) {
+    this.selectFields = fieldPaths;
+    return mockSelect(...fieldPaths) || this;
+  }
+
+  where(key, comp, value) {
+    const result = mockWhere(...arguments);
+    if (result) {
+      return result;
+    }
+
+    // Firestore has been tested to throw an error at this point when trying to compare null as a quantity
+    if (value === null && !['==', '!='].includes(comp)) {
+      throw new Error(
+        `FakeFirebaseError: Invalid query. Null only supports '==' and '!=' comparisons.`,
+      );
+    }
+    this.filters.push({ key, comp, value });
+    return result || this;
+  }
+
+  offset() {
+    return mockOffset(...arguments) || this;
+  }
+
+  limit() {
+    return mockLimit(...arguments) || this;
+  }
+
+  orderBy() {
+    return mockOrderBy(...arguments) || this;
+  }
+
+  startAfter() {
+    return mockStartAfter(...arguments) || this;
+  }
+
+  startAt() {
+    return mockStartAt(...arguments) || this;
+  }
+
+  withConverter() {
+    return mockWithConverter(...arguments) || this;
+  }
+
+  onSnapshot() {
+    mockQueryOnSnapshot(...arguments);
+    const [callback, errorCallback] = arguments;
+    try {
+      callback(this._get());
+    } catch (e) {
+      if (errorCallback) {
+        errorCallback(e);
+      } else {
+        throw e;
+      }
+    }
+
+    // Returns an unsubscribe mock
+    return mockQueryOnSnapshotUnsubscribe;
+  }
+}
+
+export const mocks = {
+  mockGet,
+  mockSelect,
+  mockWhere,
+  mockLimit,
+  mockOrderBy,
+  mockOffset,
+  mockStartAfter,
+  mockStartAt,
+  mockQueryOnSnapshot,
+  mockQueryOnSnapshotUnsubscribe,
+  mockWithConverter,
+};

package/mocks/reactNativeFirebaseFirestore.d.ts

@@ -0,0 +1,20 @@
+import type { StubOverrides, StubOptions } from './firebase.js';
+import type { FakeFirestore } from './firestore.js';
+
+declare class Firestore extends FakeFirestore {
+  constructor();
+}
+
+interface GCloudFirestoreMock {
+  Firestore: typeof Firestore;
+  Query: typeof Firestore.Query;
+  CollectionReference: typeof Firestore.CollectionReference;
+  DocumentReference: typeof Firestore.DocumentReference;
+  FieldValue: typeof Firestore.FieldValue;
+  FieldPath: typeof Firestore.FieldPath;
+  Timestamp: typeof Firestore.Timestamp;
+  Transaction: typeof Firestore.Transaction;
+}
+
+export const firestoreStub: (overrides: StubOverrides, options?: StubOptions) => GCloudFirestoreMock;
+export const mockReactNativeFirestore: (overrides: StubOverrides, options?: StubOptions) => void;