@freshfox/ng-firestore

Typesafe repositories around Firestore providing a straightforward API to read and write documents in the browser.

Usage

Installation using pnpm

pnpm add @freshfox/ng-firestore firestore-storage-core

Import FFFirestoreModule

// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    importProvidersFrom([
      FFFirestoreModule.forRootAsync({
        deps: [FIREBASE_APP],
        useFactory: (app: FirebaseApp) => {
          initializeFirestore(app, {});
          const firestore = getFirestore(app);

          // Use this to connect to an emulator locally
          if (environment.emulator) {
            connectFirestoreEmulator(firestore, window.location.hostname, 8080);
          }
          return firestore;
        }
      })
    ])
  ]
};

Define collections

To define your collection paths, refer to the following link.

https://github.com/freshfox/firestore-storage?tab=readme-ov-file#defining-collections-and-repositories

Define repositories

You need to define a repository for every collection you want to query documents from.

import { Injectable } from '@angular/core';
import { BaseRepository } from '@freshfox/ng-firestore';
import { Repository } from 'firestore-storage-core';
import { Restaurant, Collections } from '@your-organization/core';

@Injectable({
  providedIn: 'root',
})
@Repository({
  path: Collections.Restaurants,
})
export class RestaurantRepository extends BaseRepository<Restaurant, typeof Collections.Restaurants> {
}

After that, you can inject your repository anywhere within your application.

import { Injectable } from '@angular/core';
import { BaseRepository } from '@freshfox/ng-firestore';
import { Repository } from 'firestore-storage-core';
import { Restaurant, Collections } from '@your-organization/core';
import { RestaurantRepository } from "./restaurant.repo";

@Injectable({
  providedIn: 'root',
})
export class SomeService {

  constructor(private restaurantRepo: RestaurantRepository) {
  }

}

Repository Methods

The following methods are available on the repository class.

Data Retrieval

• findById(ids: DocumentIds<Path>): Retrieves a single document based on its ID(s). Returns an observable that emits the document data or null if not found.
• getById(ids: DocumentIds<Path>): Similar to findById, but throws an error if the document is not found.
• query(cb: (qb: FFQuery<T>) => FFQuery<T>, ids: CollectionIds<Path>): Constructs a Firestore query using a provided callback function for customized filtering and sorting. Returns an observable of the matching document data.
• list(attributes: ModelQuery<T> | null, ids: CollectionIds<Path>, order?: Order<T>): Retrieves a list of documents based on optional attributes and sorting criteria. Returns an observable of the document data.
• groupQuery(cb?: (qb: FFQuery<T>) => FFQuery<T>): Executes a query across all subcollections with the same name as the collection path. Returns an observable of the document data.
• count(cb: (qb: FFQuery<T>) => FFQuery<T>, ids: CollectionIds<Path>): Counts the number of documents matching a specific query. Returns a promise that resolves to the document count.

Data Manipulation

• save(data: T | ModelDataOnly<T> | PatchUpdate<ModelDataWithId<T>>, ids: CollectionIds<Path>): Saves data to a document. If no ID is provided, a new document is created. Returns a promise that resolves to the document ID.
• write(data: T | ModelDataOnly<T>, ids: CollectionIds<Path>): Overwrites existing data in a document. Returns a promise that resolves to the document ID.
• update(data: T | PatchUpdate<ModelDataWithId<T>>, ids: CollectionIds<Path>): Updates specific fields within a document. Returns a promise that resolves to the document ID.
• delete(ids: DocumentIds<Path>): Deletes a document. Returns a promise that resolves when the deletion is complete.
• batchSave(data: (T | ModelDataOnly<T> | PatchUpdate<ModelDataWithId<T>>)[], remove: { id: string }[] | null, ids: CollectionIds<Path>): Saves or deletes multiple documents in a single transaction. Returns a promise that resolves when the batch operation is complete.
• transaction<R = void>(cb: (trx: FirestoreTransaction) => Promise<R>): Executes a transaction within a Firestore transaction context. Returns a promise that resolves to the result of the transaction callback.
• generateId(): Generates a unique ID for a new document. Returns a string.