@data-weave/backend-firestore 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.3.3](https://github.com/data-weave/datamanager/compare/v0.3.2...v0.3.3) (2025-09-28)
+
+**Note:** Version bump only for package @data-weave/backend-firestore
+
+## [0.3.2](https://github.com/data-weave/datamanager/compare/v0.3.1...v0.3.2) (2025-09-28)
+
+**Note:** Version bump only for package @data-weave/backend-firestore
+
+## [0.3.1](https://github.com/data-weave/datamanager/compare/v0.3.0...v0.3.1) (2025-09-28)
+
+**Note:** Version bump only for package @data-weave/backend-firestore
+
+## 0.3.0 (2025-09-28)
+
+### Features
+
+- add code quality workflow and circular dep check ([9c7b7e3](https://github.com/data-weave/datamanager/commit/9c7b7e34501dfc95ddc2bcff686f55db06d9b1b8))
+- add transactions support ([59db0ff](https://github.com/data-weave/datamanager/commit/59db0ffce889e040828779bd2d03efe5ac088e78))
+- project re-organization ([4a00af3](https://github.com/data-weave/datamanager/commit/4a00af36c4c2f6e49287542e0d5ad85acaa50cda))
+
+### Bug Fixes
+
+- adjust config and lib versions ([9c7e2c9](https://github.com/data-weave/datamanager/commit/9c7e2c9072ea34b1e54326c2612b43c92ec2da4e))
+- adjust tests for firestore realtime snapshots ([539f314](https://github.com/data-weave/datamanager/commit/539f31448f68b084dc4e429663fe71e69c98760e))
+- implement Cache prop & clean up some of anys ([955b11a](https://github.com/data-weave/datamanager/commit/955b11a6ab05224f843db834ad28796602679fac))
+
+### Reverts
+
+- revert incorrect name change ([191e64e](https://github.com/data-weave/datamanager/commit/191e64e1123bdbc3555ff7830a532761157fd8ac))
+
+### Code Refactoring
+
+- abstract out firestoreReference into LiveReference ([7848a87](https://github.com/data-weave/datamanager/commit/7848a872155593e5acab56696d4d9f27f0e6abb2))
+- abstract out LiveList function from FirestorList ([bb4278e](https://github.com/data-weave/datamanager/commit/bb4278e960d0080d1fb18d847036acb189782ec9))
+- adjustments for LiveList & ListReference ([49cd540](https://github.com/data-weave/datamanager/commit/49cd540295693e40bbb9eb75b5101b45c6932921))
+- include namepspace in DataManager name ([9c0a171](https://github.com/data-weave/datamanager/commit/9c0a1712d8de3cef0d2e1f8022044d0ca3628ae6))

package/lib/FirestoreDataManager.ts

@@ -0,0 +1,242 @@
+import { injectable } from 'inversify'
+
+import { Cache, MapCache } from '@data-weave/datamanager/lib/Cache'
+import { CreateOptions, DataManager, Metadata, WithMetadata } from '@data-weave/datamanager/lib/DataManager'
+import { List, ListPaginationParams } from '@data-weave/datamanager/lib/List'
+import { IdentifiableReference, WithoutId } from '@data-weave/datamanager/lib/Reference'
+import { FirestoreList } from './FirestoreList'
+import {
+    FIRESTORE_KEYS,
+    FirestoreMetadataConverter,
+    FirestoreSerializedMetadata,
+    queryNotDeleted,
+} from './FirestoreMetadata'
+import { FirestoreReference } from './FirestoreReference'
+import {
+    DocumentData,
+    FilterBy,
+    FirebaseCreateOptions,
+    Firestore,
+    FirestoreDataConverter,
+    FirestoreReadMode,
+    FirestoreReadOptions,
+    FirestoreTypes,
+    FirestoreWriteOptions,
+    InternalFirestoreDataConverter,
+    OrderBy,
+    WithFieldValue,
+} from './firestoreTypes'
+import { MergeConverters, checkIfReferenceExists } from './utils'
+
+export type FirebaseDataManagerDeleteMode = 'soft' | 'hard'
+
+export interface FirebaseDataManagerOptions {
+    readonly idResolver?: () => string
+    readonly deleteMode?: FirebaseDataManagerDeleteMode
+    readonly readMode?: FirestoreReadMode
+    readonly preventOverwriteOnCreate?: boolean
+    // TODO: Add preventUpdateIfNotExists?
+    readonly Reference?: typeof FirestoreReference
+    readonly List?: typeof FirestoreList
+    readonly listCache?: Cache
+    readonly refCache?: Cache
+}
+
+const defaultFirebaseDataManagerOptions: FirebaseDataManagerOptions = {
+    deleteMode: 'soft',
+    preventOverwriteOnCreate: true,
+    readMode: 'static',
+    Reference: FirestoreReference,
+    List: FirestoreList,
+}
+
+export interface QueryParams<T extends FirestoreTypes.DocumentData> {
+    readonly filters?: Array<FilterBy<T & FirestoreSerializedMetadata>>
+    readonly orderBy?: Array<OrderBy<T & FirestoreSerializedMetadata>>
+}
+
+@injectable()
+export class FirestoreDataManager<
+    T extends FirestoreTypes.DocumentData,
+    SerializedT extends FirestoreTypes.DocumentData,
+> implements DataManager<T>
+{
+    private mergedConverter: InternalFirestoreDataConverter<T & Metadata, SerializedT & FirestoreSerializedMetadata>
+    private collection: FirestoreTypes.CollectionReference<T & Metadata, SerializedT & FirestoreSerializedMetadata>
+    private collectionQuery: FirestoreTypes.Query<T & Metadata, SerializedT & FirestoreSerializedMetadata>
+    private managerOptions: FirebaseDataManagerOptions
+
+    private refCache: Cache<string, IdentifiableReference<WithMetadata<T>>>
+    private listCache: Cache<string, List<WithMetadata<T>>>
+
+    constructor(
+        private readonly firestore: Firestore,
+        private readonly collectionPath: string,
+        private readonly converter: FirestoreDataConverter<T, SerializedT>,
+        private readonly opts?: FirebaseDataManagerOptions
+    ) {
+        // @ts-expect-error - Force merge FirestoreDataConverter and InternalFirestoreDataConverter
+        this.mergedConverter = new MergeConverters(this.converter, new FirestoreMetadataConverter())
+        this.managerOptions = Object.assign(defaultFirebaseDataManagerOptions, this.opts)
+
+        this.refCache = this.managerOptions.refCache || new MapCache(100)
+        this.listCache = this.managerOptions.listCache || new MapCache(100)
+
+        this.collection = this.firestore
+            .collection(this.firestore.app, this.collectionPath)
+            .withConverter(this.mergedConverter)
+
+        this.collectionQuery =
+            this.managerOptions.deleteMode === 'soft'
+                ? queryNotDeleted(this.collection, this.firestore.query, this.firestore.where)
+                : this.collection
+    }
+
+    public async read(id: string, options?: FirestoreReadOptions): Promise<WithMetadata<T> | undefined> {
+        if (!this.managerOptions?.Reference) throw new Error('ReferenceClass not defined')
+
+        const ref = this.getRef(id)
+
+        if (options?.transaction) {
+            const snapshot = await options.transaction.get<WithMetadata<T>, DocumentData>(
+                this.firestore.doc(this.collection, id)
+            )
+            if (!checkIfReferenceExists(snapshot)) return undefined
+            return snapshot.data()
+        }
+        return await ref.resolve()
+    }
+
+    public async create(data: WithFieldValue<WithoutId<T>>, options?: FirebaseCreateOptions) {
+        let id: string | undefined = undefined
+        if (options?.id) {
+            id = options?.id
+        } else if (this.managerOptions?.idResolver) {
+            id = this.managerOptions.idResolver()
+        }
+
+        let docRef: FirestoreTypes.DocumentReference
+        let docExists: boolean = false
+
+        if (id) {
+            docRef = this.firestore.doc(this.collection, id)
+            docExists = await this.preventOverwriteOnCreate(docRef, options)
+        } else {
+            docRef = this.firestore.doc(this.collection)
+        }
+
+        const docDataWithMetadata = {
+            ...data,
+            [FIRESTORE_KEYS.CREATED_AT]: docExists ? undefined : this.firestore.serverTimestamp(),
+            [FIRESTORE_KEYS.UPDATED_AT]: this.firestore.serverTimestamp(),
+            [FIRESTORE_KEYS.DELETED]: false,
+        }
+
+        const firebaseOptions = { merge: options?.merge }
+
+        if (options?.transaction) {
+            options?.transaction.set(docRef, docDataWithMetadata, firebaseOptions)
+        } else {
+            await this.firestore.setDoc(docRef, docDataWithMetadata, firebaseOptions)
+        }
+
+        return this.getRef(docRef.id)
+    }
+
+    private async _update(
+        id: string,
+        data: WithoutId<Partial<WithFieldValue<T & Metadata>>>,
+        options?: FirestoreWriteOptions
+    ) {
+        const extendedData = {
+            ...data,
+            [FIRESTORE_KEYS.UPDATED_AT]: this.firestore.serverTimestamp(),
+        }
+        // Firestore update method doesn't call converter like setDoc does, so we need to serialize the data manually.
+        const serializedData = this.mergedConverter.toFirestore(extendedData)
+
+        const ref = this.firestore.doc(this.collection, id)
+
+        if (options?.transaction) {
+            return options.transaction.update<DocumentData, DocumentData>(ref, serializedData)
+        }
+        return this.firestore.updateDoc(ref, serializedData)
+    }
+
+    public async update(id: string, data: WithoutId<Partial<WithFieldValue<T>>>, options?: FirestoreWriteOptions) {
+        await this._update(id, data, options)
+    }
+
+    public async upsert(id: string, data: WithFieldValue<WithoutId<T>>, options?: FirestoreWriteOptions) {
+        this.create(data, { ...options, id, merge: true })
+    }
+
+    public async delete(id: string, options?: FirestoreWriteOptions) {
+        if (this.managerOptions.deleteMode === 'soft') {
+            await this._update(
+                id,
+                {
+                    ...({} as Partial<T>),
+                    [FIRESTORE_KEYS.DELETED]: true,
+                },
+                options
+            )
+            return
+        }
+        return this.firestore.deleteDoc(this.firestore.doc(this.collection, id))
+    }
+
+    public getRef(id: string) {
+        if (!this.managerOptions?.Reference) throw new Error('ReferenceClass not defined')
+
+        if (this.refCache.has(id)) {
+            return this.refCache.get(id)!
+        }
+
+        const newRef = new this.managerOptions.Reference(this.firestore, this.firestore.doc(this.collection, id), {
+            readMode: this.managerOptions.readMode,
+        })
+        this.refCache.set(id, newRef)
+        return newRef
+    }
+
+    private _getFilteredQuery(params?: QueryParams<SerializedT>) {
+        let compoundQuery = this.collectionQuery
+
+        params?.filters?.forEach(filter => {
+            compoundQuery = this.firestore.query(compoundQuery, this.firestore.where(filter[0], filter[1], filter[2]))
+        })
+
+        params?.orderBy?.forEach(orderBy => {
+            compoundQuery = this.firestore.query(compoundQuery, this.firestore.orderBy(orderBy[0], orderBy[1]))
+        })
+
+        return compoundQuery
+    }
+
+    public getList(params?: QueryParams<SerializedT> & ListPaginationParams) {
+        if (!this.managerOptions.List) throw new Error('ListClass not defined')
+
+        const compoundQuery = this._getFilteredQuery(params)
+
+        const key = JSON.stringify(params || {})
+        if (this.listCache.has(key)) {
+            return this.listCache.get(key)!
+        }
+        const newList = new this.managerOptions.List(this.firestore, compoundQuery, {
+            readMode: this.managerOptions.readMode,
+            ...params,
+        })
+        this.listCache.set(key, newList)
+        return newList
+    }
+
+    private async preventOverwriteOnCreate(docRef: FirestoreTypes.DocumentReference, createOptions?: CreateOptions) {
+        const doc = await this.firestore.getDoc(docRef)
+        const docExists = checkIfReferenceExists(doc)
+        if (docExists && this.managerOptions.preventOverwriteOnCreate && createOptions?.merge !== true) {
+            throw new Error(`Document already exists - ${doc.ref.path}`)
+        }
+        return docExists
+    }
+}

package/lib/FirestoreList.ts

@@ -0,0 +1,84 @@
+import { ListPaginationParams, LiveList, LiveListOptions } from '@data-weave/datamanager'
+import { DocumentData, Firestore, FirestoreReadMode, FirestoreTypes } from './firestoreTypes'
+
+export interface FirestoreListOptions<T> extends LiveListOptions<T> {
+    readMode?: FirestoreReadMode
+}
+
+export class FirestoreList<T extends DocumentData, S extends DocumentData> extends LiveList<T> {
+    private unsubscribeFromSnapshot: undefined | (() => void)
+
+    constructor(
+        private readonly firestore: Firestore,
+        private readonly query: FirestoreTypes.Query<T, S>,
+        private readonly options: FirestoreListOptions<T> & ListPaginationParams
+    ) {
+        super(options)
+    }
+
+    public async resolve() {
+        if (this.options?.readMode === 'realtime') {
+            let initialLoad = true
+            return new Promise<T[]>((resolve, reject) => {
+                this.unsubscribeFromSnapshot = this.firestore.onSnapshot(
+                    this.query,
+                    querySnapshot => {
+                        try {
+                            if (initialLoad) {
+                                initialLoad = false
+                                this.handleInitialDataChange(querySnapshot.docs)
+                            } else {
+                                this.handleSubsequentDataChanges(querySnapshot.docChanges())
+                            }
+                            // TODO: When calling ".resolve()" with realtime listener,
+                            // the snapshot data might be stale from cache.
+                            resolve(this.values)
+                        } catch (error) {
+                            this.onError(error)
+                            reject(error)
+                        }
+                    },
+                    error => {
+                        this.onError(error)
+                        reject(error)
+                    }
+                )
+            })
+        } else {
+            const snapshot = await this.firestore.getDocs(this.query)
+            this.handleInitialDataChange(snapshot.docs)
+            return this.values
+        }
+    }
+
+    protected handleInitialDataChange(values: FirestoreTypes.QueryDocumentSnapshot<T, S>[]) {
+        const newValues = values.map(v => v.data())
+        this.onUpdateAll(newValues)
+    }
+
+    protected handleSubsequentDataChanges(changes: FirestoreTypes.DocumentChange<T, S>[]) {
+        changes.forEach(change => {
+            if (change.type === 'added') {
+                this.onAddAtIndex(change.newIndex, change.doc.data())
+            } else if (change.type === 'modified') {
+                this.onUpdateAtIndex(change.newIndex, change.doc.data())
+            } else if (change.type === 'removed') {
+                this.onRemoveAtIndex(change.oldIndex)
+            }
+        })
+        // TODO: handle onUpdate in the parent class - make sure it's only called once after all changes are processed
+        this.onUpdate()
+    }
+
+    public unSubscribe() {
+        this.unsubscribeFromSnapshot?.()
+        this.setStale()
+    }
+
+    protected onError(error: unknown) {
+        // Try to provide useful collection details using internal properties
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        console.error(`FirestoreList Collection: ${(this.query as any)?._collectionPath?.id} error`, error)
+        super.onError(error)
+    }
+}

package/lib/FirestoreMetadata.ts

@@ -0,0 +1,59 @@
+import { Metadata, WithoutId } from '@data-weave/datamanager'
+import {
+    DocumentData,
+    FirestoreQuery,
+    FirestoreTypes,
+    FirestoreWhere,
+    InternalFirestoreDataConverter,
+    WithFieldValue,
+} from './firestoreTypes'
+
+enum FIRESTORE_INTERAL_KEYS {
+    DELETED = '__deleted',
+    CREATED_AT = '__createdAt',
+    UPDATED_AT = '__updatedAt',
+}
+
+export enum FIRESTORE_KEYS {
+    DELETED = 'deleted',
+    CREATED_AT = 'createdAt',
+    UPDATED_AT = 'updatedAt',
+}
+
+export type FirestoreSerializedMetadata = {
+    [FIRESTORE_INTERAL_KEYS.DELETED]: boolean
+    [FIRESTORE_INTERAL_KEYS.CREATED_AT]: FirestoreTypes.Timestamp
+    [FIRESTORE_INTERAL_KEYS.UPDATED_AT]: FirestoreTypes.Timestamp
+}
+
+export class FirestoreMetadataConverter
+    implements InternalFirestoreDataConverter<Metadata, FirestoreSerializedMetadata>
+{
+    toFirestore(data: WithFieldValue<WithoutId<Metadata>>) {
+        return {
+            [FIRESTORE_INTERAL_KEYS.DELETED]: data[FIRESTORE_KEYS.DELETED],
+            // Cast: Firestore handles conversion from Date to Timestamp internally
+            [FIRESTORE_INTERAL_KEYS.CREATED_AT]: data[FIRESTORE_KEYS.CREATED_AT] as unknown as FirestoreTypes.Timestamp,
+            [FIRESTORE_INTERAL_KEYS.UPDATED_AT]: data[FIRESTORE_KEYS.UPDATED_AT] as unknown as FirestoreTypes.Timestamp,
+        }
+    }
+    fromFirestore(
+        snapshot: FirestoreTypes.QueryDocumentSnapshot<DocumentData, DocumentData>,
+        options: FirestoreTypes.SnapshotOptions
+    ) {
+        const data = snapshot.data(options) as FirestoreSerializedMetadata
+        return {
+            id: snapshot.ref.id,
+            // TODO: add warning in case data type is not as expected
+            createdAt: data[FIRESTORE_INTERAL_KEYS.CREATED_AT]?.toDate(),
+            updatedAt: data[FIRESTORE_INTERAL_KEYS.UPDATED_AT]?.toDate(),
+            deleted: data[FIRESTORE_INTERAL_KEYS.DELETED],
+        }
+    }
+}
+
+export const queryNotDeleted = <T extends DocumentData, SerializedT extends DocumentData>(
+    query: FirestoreTypes.Query<T, SerializedT>,
+    firestoreQuery: FirestoreQuery<T, SerializedT>,
+    firestoreWhere: FirestoreWhere
+) => firestoreQuery(query, firestoreWhere(FIRESTORE_INTERAL_KEYS.DELETED, '==', false))

package/lib/FirestoreReference.ts

@@ -0,0 +1,75 @@
+import { LiveReference, LiveReferenceOptions } from '@data-weave/datamanager'
+import { DocumentData, Firestore, FirestoreReadMode, FirestoreTypes } from './firestoreTypes'
+import { checkIfReferenceExists } from './utils'
+
+export interface FirestoreReferenceOptions<T> extends LiveReferenceOptions<T> {
+    readMode?: FirestoreReadMode
+}
+
+export class FirestoreReference<T extends DocumentData, S extends DocumentData> extends LiveReference<T> {
+    private unsubscribeFromSnapshot: undefined | (() => void)
+
+    constructor(
+        private readonly firestore: Firestore,
+        private readonly docRef: FirestoreTypes.DocumentReference<T, S>,
+        readonly options: FirestoreReferenceOptions<T>
+    ) {
+        super(options)
+    }
+
+    public async resolve(): Promise<T | undefined> {
+        if (this.options?.readMode === 'realtime') {
+            return new Promise<T | undefined>((res, reject) => {
+                this.unsubscribeFromSnapshot = this.firestore.onSnapshot(
+                    this.docRef,
+                    documentSnapshot => {
+                        try {
+                            this.onUpdate(this.parseDocumentSnapshot(documentSnapshot))
+                            // TODO: When calling ".resolve()" with realtime listener,
+                            // the snapshot data might be stale from cache.
+                            res(this.value)
+                        } catch (error) {
+                            this.onError(error)
+                            reject(error)
+                        }
+                    },
+                    error => {
+                        this.onError(error)
+                        reject(error)
+                    }
+                )
+            })
+        }
+        try {
+            const doc = await this.firestore.getDoc(this.docRef)
+            this.onUpdate(this.parseDocumentSnapshot(doc))
+        } catch (error) {
+            this.onError(error)
+            throw error
+        }
+        return this.value
+    }
+
+    public get id(): string {
+        return this.docRef.id
+    }
+
+    public get path(): string {
+        return this.docRef.path
+    }
+
+    protected onError(error: unknown): void {
+        console.error(`FirestoreReference error ${this.docRef.path}`, error)
+        super.onError(error)
+    }
+
+    public unSubscribe() {
+        this.unsubscribeFromSnapshot?.()
+        this.setStale()
+    }
+
+    private parseDocumentSnapshot(docSnapshot: FirestoreTypes.DocumentSnapshot<T, S>): T | undefined {
+        if (!checkIfReferenceExists(docSnapshot)) throw new Error(`Document does not exist ${this.docRef.path}`)
+        return docSnapshot.data()
+    }
+}

package/lib/firestoreTypes.ts

@@ -0,0 +1,231 @@
+import { WithoutId } from '@data-weave/datamanager'
+import type FirestoreTypes from '@firebase/firestore'
+import type { FieldPath, WithFieldValue as FirestoreWithFieldValue, QueryConstraint } from '@firebase/firestore'
+import type { HttpsCallable, HttpsCallableOptions } from '@firebase/functions-types'
+import { FieldValue, Transaction } from '@google-cloud/firestore'
+import { injectable } from 'inversify'
+
+export type DocumentData = FirestoreTypes.DocumentData
+
+export { FieldValue, FirestoreTypes, Transaction }
+
+/**
+ * Same as Partial but all fields are required to be included
+ */
+type OptionallyUndefined<T> = { [P in keyof T]: T[P] | undefined }
+
+export declare interface InternalFirestoreDataConverter<
+    T extends DocumentData,
+    SerializedT extends DocumentData = DocumentData,
+> {
+    toFirestore(
+        modelObject: Partial<WithFieldValue<WithoutId<T>>>,
+        options?: FirestoreTypes.SetOptions
+    ): WithFieldValue<WithoutId<SerializedT>>
+    fromFirestore(
+        snapshot: FirestoreTypes.QueryDocumentSnapshot<T, SerializedT>,
+        options?: FirestoreTypes.SnapshotOptions
+    ): T
+}
+
+/**
+ * Converts data between model and serialized data. Differs from InternalFirestoreDataConverter
+ * by using `OptionallyUndefined` and `Required` to ensure that all fields are included in de/serialization
+ * even if some model defined properties are optional.
+ */
+export declare interface FirestoreDataConverter<
+    T extends DocumentData,
+    SerializedT extends DocumentData = DocumentData,
+> {
+    toFirestore(
+        modelObject: WithoutId<Partial<WithFieldValue<T>>>,
+        options?: FirestoreTypes.SetOptions
+    ): OptionallyUndefined<Required<WithoutId<WithFieldValue<SerializedT>>>>
+    fromFirestore(
+        snapshot: FirestoreTypes.QueryDocumentSnapshot<T, SerializedT>,
+        options?: FirestoreTypes.SnapshotOptions
+    ): OptionallyUndefined<Required<WithoutId<T>>>
+}
+
+export type FirestoreQuery<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData> = (
+    reference: FirestoreTypes.Query<AppModelType, DbModelType>,
+    filter: any
+) => FirestoreTypes.Query<AppModelType, DbModelType>
+export type FirestoreWhere = (field: string | FieldPath, op: string, value: unknown) => any
+
+export type FirestoreReadMode = 'realtime' | 'static'
+
+export interface FirestoreReadOptions {
+    readonly transaction?: FirestoreTypes.Transaction
+}
+
+export interface FirestoreWriteOptions {
+    readonly transaction?: FirestoreTypes.Transaction
+    readonly batcher?: FirestoreTypes.WriteBatch
+}
+
+export interface FirebaseCreateOptions extends FirestoreWriteOptions {
+    id?: string
+    merge?: boolean
+}
+
+export declare type WithFieldValue<T> = {
+    [K in keyof T]: FirestoreWithFieldValue<T[K]> | FirestoreTypes.FieldValue
+}
+
+type GenNode<K extends string, IsRoot extends boolean> = IsRoot extends true ? `${K}` : `.${K}`
+
+export type FilterableFields<
+    T extends object,
+    IsRoot extends boolean = true,
+    K extends keyof T = keyof T,
+> = K extends string
+    ? // Handle firebase timestamp fields
+      T[K] extends FirestoreTypes.Timestamp
+        ? `${K}`
+        : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          T[K] extends any[]
+          ? GenNode<K, IsRoot>
+          : T[K] extends object
+            ? `${GenNode<K, IsRoot>}${FilterableFields<T[K], false>}`
+            : GenNode<K, IsRoot>
+    : never
+
+type GetValue<T, K extends string> = K extends `${infer L}.${infer R}`
+    ? L extends keyof T
+        ? GetValue<T[L], R>
+        : never
+    : K extends keyof T
+      ? T[K]
+      : K extends string
+        ? string | number | boolean
+        : never
+
+export type PrimitiveFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>'
+
+export type FilterBy<T extends object, Field extends string = FilterableFields<T>> = Field extends string
+    ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      GetValue<T, Field> extends any[]
+        ? [Field, 'array-contains', string] | [Field, 'array-contains-any', string[]]
+        : [Field, PrimitiveFilterOp, GetValue<T, Field>] | [Field, 'in', string[]]
+    : never
+
+export type OrderBy<T extends DocumentData, Fields extends string = FilterableFields<T>> = [
+    Fields,
+    FirestoreTypes.OrderByDirection,
+]
+
+export abstract class FieldValues {
+    public abstract serverTimestamp(): FirestoreTypes.FieldValue
+    public abstract delete(): FirestoreTypes.FieldValue
+    public abstract increment(n: number): FirestoreTypes.FieldValue
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    public abstract arrayUnion(...elements: any[]): FirestoreTypes.FieldValue
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    public abstract arrayRemove(...elements: any[]): FirestoreTypes.FieldValue
+}
+
+/**********
+ *
+ *
+ * INJECTABLES
+ *
+ *
+ * **********/
+
+export interface FirestoreAppSettings {
+    persistence?: boolean
+    cacheSizeBytes?: number
+    host?: string
+    ssl?: boolean
+    ignoreUndefinedProperties?: boolean
+    serverTimestampBehavior?: 'estimate' | 'previous' | 'none'
+}
+
+export abstract class FirestoreApp {
+    public abstract type?: string
+    public abstract toJSON?(): object
+    public abstract terminate?(): Promise<void>
+    public abstract settings?(settings: FirestoreAppSettings): void
+    public abstract useEmulator?(host: string, port: number): void
+    public abstract runTransaction?<T>(
+        updateFunction: (transaction: Transaction) => Promise<T>,
+        options?: FirestoreTypes.TransactionOptions
+    ): Promise<T>
+}
+
+@injectable()
+export abstract class Firestore {
+    public abstract app: FirestoreApp
+    public abstract collection(reference: FirestoreTypes.CollectionReference | FirestoreApp, path: string): any
+    public abstract getDocs<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.Query<AppModelType, DbModelType>
+    ): Promise<FirestoreTypes.QuerySnapshot<AppModelType, DbModelType>>
+    public abstract getDoc<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.DocumentReference<AppModelType, DbModelType>,
+        path?: string
+    ): Promise<FirestoreTypes.DocumentSnapshot<AppModelType, DbModelType>>
+    public abstract serverTimestamp(): FirestoreTypes.FieldValue
+    public abstract increment(n: number): FirestoreTypes.FieldValue
+    public abstract query<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.Query<AppModelType, DbModelType>,
+        filter: any
+    ): FirestoreTypes.Query<AppModelType, DbModelType>
+    public abstract where(field: string | FieldPath, op: string, value: unknown): QueryConstraint
+    public abstract limit(limit: number): any
+    public abstract orderBy(orderBy: string, direction: FirestoreTypes.OrderByDirection): any
+    public abstract setDoc<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.DocumentReference<AppModelType, DbModelType>,
+        data: any,
+        options?: FirestoreTypes.SetOptions
+    ): Promise<void>
+    public abstract updateDoc<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.DocumentReference<AppModelType, DbModelType>,
+        data: any
+    ): Promise<void>
+    public abstract doc<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.Query<AppModelType, DbModelType>,
+        path?: string
+    ): FirestoreTypes.DocumentReference<AppModelType, DbModelType>
+    public abstract deleteDoc<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.DocumentReference<AppModelType, DbModelType>
+    ): Promise<void>
+    public abstract onSnapshot<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.DocumentReference<AppModelType, DbModelType>,
+        onNext: (snapshot: FirestoreTypes.DocumentSnapshot<AppModelType, DbModelType>) => void,
+        onError?: (error: Error) => void
+    ): () => void
+    public abstract onSnapshot<AppModelType = DocumentData, DbModelType extends DocumentData = DocumentData>(
+        reference: FirestoreTypes.Query<AppModelType, DbModelType>,
+        onNext: (snapshot: FirestoreTypes.QuerySnapshot<AppModelType, DbModelType>) => void,
+        onError?: (error: Error) => void
+    ): () => void
+    public abstract runTransaction<T>(
+        firestore: FirestoreApp,
+        transaction: (transaction: Transaction) => Promise<T>,
+        options?: FirestoreTypes.TransactionOptions
+    ): Promise<T>
+}
+
+@injectable()
+export abstract class FirestoreSettings {
+    public abstract readMode: FirestoreReadMode
+}
+
+@injectable()
+export abstract class FirestoreFunctions {
+    public abstract httpsCallable(name: string, options?: HttpsCallableOptions): HttpsCallable
+    public abstract useEmulator(host: string, port: number): void
+    public abstract useFunctionsEmulator(origin: string): void
+}
+
+@injectable()
+export class DummyFirestoreFunctions implements FirestoreFunctions {
+    public httpsCallable(): HttpsCallable {
+        return () => {
+            throw new Error('httpsCallable not implemented - DummyFirestoreFunctions')
+        }
+    }
+    public useEmulator() {}
+    public useFunctionsEmulator() {}
+}

package/lib/index.ts

@@ -0,0 +1,6 @@
+export * from './FirestoreDataManager'
+export * from './FirestoreList'
+export * from './FirestoreMetadata'
+export * from './FirestoreReference'
+export * from './firestoreTypes'
+export * from './utils'

package/lib/utils.ts

@@ -0,0 +1,179 @@
+import { WithoutId } from '@data-weave/datamanager'
+import {
+    DocumentData,
+    FieldValues,
+    Firestore,
+    FirestoreApp,
+    FirestoreTypes,
+    InternalFirestoreDataConverter,
+    Transaction,
+    WithFieldValue,
+} from './firestoreTypes'
+
+export class MergeConverters<
+    T extends DocumentData,
+    SerializedT extends DocumentData,
+    G extends DocumentData,
+    SerializedG extends DocumentData,
+> implements InternalFirestoreDataConverter<T & G, SerializedT & SerializedG>
+{
+    constructor(
+        private converter1: InternalFirestoreDataConverter<T, SerializedT>,
+        private converter2: InternalFirestoreDataConverter<G, SerializedG>
+    ) {}
+
+    toFirestore(
+        modelObject: WithoutId<Partial<WithFieldValue<T>>> & WithoutId<Partial<WithFieldValue<G>>>,
+        options?: FirestoreTypes.SetOptions
+    ) {
+        if (options) {
+            return {
+                ...this.converter1.toFirestore(modelObject, options),
+                ...this.converter2.toFirestore(modelObject, options),
+            }
+        } else {
+            return {
+                ...this.converter1.toFirestore(modelObject),
+                ...this.converter2.toFirestore(modelObject),
+            }
+        }
+    }
+
+    fromFirestore(
+        snapshot: FirestoreTypes.QueryDocumentSnapshot<T & G, SerializedT & SerializedG>,
+        options: FirestoreTypes.SnapshotOptions
+    ) {
+        return {
+            ...this.converter1.fromFirestore(snapshot, options),
+            ...this.converter2.fromFirestore(snapshot, options),
+        }
+    }
+}
+
+/*
+ *  FirestoreNamespacedConverter creates an interface between modular and namespaced
+ *  firestore libraries.
+ *   - admin sdk doesn't support modular imports
+ */
+
+// TODO: add types
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export class FirestoreNamespacedConverter extends Firestore {
+    public app: FirestoreApp
+    constructor(
+        readonly firestore: FirestoreApp,
+        readonly fieldValues: FieldValues
+    ) {
+        super()
+        this.app = firestore
+        this.fieldValues = fieldValues
+    }
+
+    public collection(reference: any, path: string) {
+        return reference.collection(path)
+    }
+
+    public getDocs(reference: any) {
+        return reference.get()
+    }
+
+    public getDoc(reference: any, path?: string) {
+        return reference.get(path)
+    }
+
+    public serverTimestamp() {
+        return this.fieldValues.serverTimestamp()
+    }
+
+    public increment(n: number) {
+        return this.fieldValues.increment(n)
+    }
+
+    public query(reference: any, filter: any) {
+        if (filter.type === 'where') {
+            return reference.where(filter.field, filter.op, filter.value)
+        }
+        if (filter.type === 'orderBy') {
+            return reference.orderBy(filter.field, filter.direction)
+        }
+        if (filter.type === 'limit') {
+            return reference.limit(filter.limit)
+        }
+    }
+
+    public where(field: string | FirestoreTypes.FieldPath, op: string, value: unknown): any {
+        return {
+            type: 'where',
+            field,
+            op,
+            value,
+        }
+    }
+
+    public limit(limit: number) {
+        return {
+            type: 'limit',
+            limit,
+        }
+    }
+
+    public orderBy(orderBy: string, direction: FirestoreTypes.OrderByDirection) {
+        return {
+            type: 'orderBy',
+            orderBy,
+            direction,
+        }
+    }
+
+    public setDoc(reference: any, data: any, options?: FirestoreTypes.SetOptions) {
+        return reference.set(data, options)
+    }
+
+    public updateDoc(reference: any, data: any) {
+        return reference.update(data)
+    }
+
+    public deleteDoc(reference: any) {
+        return reference.delete()
+    }
+
+    public doc(reference: any, path?: string) {
+        if (!path) return reference.doc()
+        return reference.doc(path)
+    }
+
+    public onSnapshot(reference: any, onNext: (snapshot: any) => void, onError?: (error: Error) => void) {
+        return reference.onSnapshot(onNext, onError)
+    }
+
+    public runTransaction<T>(
+        firestore: FirestoreApp,
+        transaction: (transaction: Transaction) => Promise<T>,
+        options?: FirestoreTypes.TransactionOptions
+    ) {
+        return firestore.runTransaction!(transaction, options)
+    }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+// Value can be anything
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const isFieldValue = (value: any): value is FirestoreTypes.FieldValue => {
+    return value !== undefined && typeof value._toFieldTransform === 'function'
+}
+
+// Modular firestore uses exists, namespaced uses exists()
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const checkIfReferenceExists = (value: any): boolean => {
+    if (value == null) return false
+    if (typeof value.exists === 'function') return value.exists()
+    return value.exists
+}
+
+export const withTransaction = (
+    firestore: Firestore,
+    transaction: (transaction: Transaction) => Promise<void>,
+    options?: FirestoreTypes.TransactionOptions
+) => {
+    return firestore.runTransaction!(firestore.app, transaction, options)
+}

package/lib/version.js

@@ -0,0 +1,2 @@
+// Generated by genversion.
+module.exports = '0.3.3';

package/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "@data-weave/backend-firestore",
+    "version": "0.3.3",
+    "author": "",
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "scripts": {
+        "build": "genversion --semi lib/version.js",
+        "build:clean": "rimraf android/build && rimraf ios/build",
+        "prepare": "npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/data-weave/datamanager/tree/master/packages/backend-firestore"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "dependencies": {
+        "firebase": "^11.9.0",
+        "firebase-admin": "^13.0.2"
+    },
+    "peerDependencies": {
+        "@data-weave/datamanager": "0.3.2"
+    },
+    "gitHead": "4fc18c650dcea3f3ede1cf2b413399656f90b79a"
+}