Fire

Servicios de Angular para inicializar las instancias de Firebase App, Auth, Firestore y Storage. Las operaciones de autenticacion, lectura, escritura y archivos se realizan directamente con el SDK oficial de Firebase.

npm i @ourcodeng/fire firebase

@ourcodeng/fire asume que la aplicacion ya tiene Angular configurado y que provee las opciones de Firebase del proyecto.

Exportaciones

Importa los inicializadores, constantes y tipos desde @ourcodeng/fire:

import {
  FirebaseService,
  FireAuthService,
  FirestoreService,
  FireStorageService,
  FIRESTORE_DEFAULT_DB_NAME,
  type FirebaseEmulatorConfig,
  type InitDbData,
  type FirestoreUpdateData,
} from "@ourcodeng/fire";

Importa las operaciones de Auth, Firestore y Storage desde sus modulos de firebase.

Inicializacion

Inicializa Firebase una sola vez al arrancar la aplicacion y antes de resolver las instancias dependientes.

import { inject, Injectable } from "@angular/core";
import {
  FirebaseService,
  FireAuthService,
  FirestoreService,
  FireStorageService,
  FIRESTORE_DEFAULT_DB_NAME,
  type FirebaseEmulatorConfig,
} from "@ourcodeng/fire";
import {
  browserPopupRedirectResolver,
  indexedDBLocalPersistence,
} from "firebase/auth";
import { environment } from "../environments/environment";

@Injectable({ providedIn: "root" })
export class FirebaseBootstrapService {
  private readonly firebase = inject(FirebaseService);
  private readonly auth = inject(FireAuthService);
  private readonly firestore = inject(FirestoreService);
  private readonly storage = inject(FireStorageService);

  init(): void {
    const emulatorConfig: FirebaseEmulatorConfig = {
      auth: { host: "localhost", port: 9099 },
      firestore: { host: "localhost", port: 8080 },
      storage: { host: "localhost", port: 9199 },
    };

    this.firebase.init(
      environment.firebase,
      environment.useFirebaseEmulators,
      emulatorConfig,
    );

    this.auth.init({
      persistence: indexedDBLocalPersistence,
      popupRedirectResolver: browserPopupRedirectResolver,
    });
    this.firestore.init({
      name: FIRESTORE_DEFAULT_DB_NAME,
      settings: {},
    });
    this.storage.init();
  }
}

Secuencia de inicializacion:

1. firebaseService.init(firebaseOptions, enableEmulators?, emulatorConfig?)
2. fireAuthService.init(dependencies?)
3. firestoreService.init(initDbData)
4. fireStorageService.init()

El primer paso es obligatorio antes de cualquiera de los demas; Auth, Firestore y Storage no dependen entre si. Solo inicializa los productos que utilice la aplicacion. enableEmulators es el interruptor que activa los emuladores; emulatorConfig solo define host y puerto.

FirebaseService

Inicializa y expone la instancia base de Firebase.

firebaseService.init(firebaseOptions);
const app = firebaseService.getApp();

API:

• init(options, enableEmulators?, emulatorConfig?): void
• getApp(): FirebaseApp

Las llamadas posteriores a init(...) no crean otra app. getApp() lanza Firebase app is not initialized si se usa antes de inicializarla.

Auth

FireAuthService solo inicializa y expone la instancia de Firebase Auth.

fireAuthService.init();
const auth = fireAuthService.getInstance();

API:

• init(dependencies?: Dependencies): void
• getInstance(): Auth

Pasa un objeto Dependencies del SDK cuando necesites controlar la persistencia o el resolver de popup/redirect:

import {
  browserPopupRedirectResolver,
  browserSessionPersistence,
} from "firebase/auth";

fireAuthService.init({
  persistence: browserSessionPersistence,
  popupRedirectResolver: browserPopupRedirectResolver,
});

Las siguientes llamadas a init(...) reutilizan la instancia existente y no cambian sus dependencias. getInstance() lanza Auth instance not initialized. Call init() first. si se usa antes de inicializar Auth.

Operaciones con el SDK de Firebase Auth

Consume la instancia con las funciones oficiales del SDK:

import {
  GoogleAuthProvider,
  createUserWithEmailAndPassword,
  getIdTokenResult,
  onAuthStateChanged,
  signInWithPopup,
} from "firebase/auth";

const auth = fireAuthService.getInstance();

const unsubscribe = onAuthStateChanged(auth, (user) => {
  console.log(user?.email);
});

await createUserWithEmailAndPassword(auth, email, password);
await signInWithPopup(auth, new GoogleAuthProvider());

if (auth.currentUser) {
  const token = await auth.currentUser.getIdToken();
  const claims = (await getIdTokenResult(auth.currentUser)).claims;
}

unsubscribe();

@ourcodeng/fire no incluye servicios de estado de usuario, tokens, email y password, Google o Facebook. Usa auth.currentUser, onAuthStateChanged y las funciones/proveedores de firebase/auth que requiera la aplicacion.

Firestore

FirestoreService crea una o varias instancias de Firestore y las recupera por nombre de base de datos.

const databases: InitDbData[] = [
  { name: FIRESTORE_DEFAULT_DB_NAME, settings: {} },
  { name: "analytics", settings: {} },
];

firestoreService.init(databases);

const db = firestoreService.getDbInstance();
const analyticsDb = firestoreService.getDbInstance("analytics");

API:

• init(initDbData: InitDbData | InitDbData[]): void
• getDbInstance(dbName?: string): Firestore

Cada elemento de initDbData contiene name y settings. settings se pasa directamente a initializeFirestore del SDK de Firebase, por lo que permite configurar la instancia de cada base de datos.

Notas:

• Pasa FIRESTORE_DEFAULT_DB_NAME o "(default)" en name para crear la base predeterminada.
• Puedes inicializar nombres nuevos en llamadas posteriores, pero repetir un nombre lanza FirestoreService is already initialized for dbName: ....
• getDbInstance() usa la base predeterminada cuando se omite el nombre.
• Resolver una instancia antes de inicializar Firestore o solicitar un nombre desconocido lanza un error descriptivo.

Usa la instancia con el SDK oficial:

import { collection, getDocs } from "firebase/firestore";

const db = firestoreService.getDbInstance();
const snapshot = await getDocs(collection(db, "users"));

FirestoreUpdateData permite valores FieldValue, objetos parciales, null o undefined en objetos de actualizacion.

import { doc, serverTimestamp, updateDoc } from "firebase/firestore";
import type { FirestoreUpdateData } from "@ourcodeng/fire";

const data: FirestoreUpdateData = {
  displayName: "Ada",
  updatedAt: serverTimestamp(),
};

await updateDoc(doc(db, "users", userId), data);

Storage

FireStorageService inicializa Firebase Storage y expone su instancia.

const storage = fireStorageService.init();
const sameStorage = fireStorageService.getInstance();

API:

• init(): FirebaseStorage
• getInstance(): FirebaseStorage

init() es idempotente. getInstance() lanza FirebaseStorage instance not initialized. Call init() first. si se usa antes de inicializar Storage.

Usa la instancia con el SDK oficial:

import { ref, uploadBytes } from "firebase/storage";

const storage = fireStorageService.getInstance();
const fileRef = ref(storage, `avatars/${userId}.png`);

await uploadBytes(fileRef, file);

Emuladores

La configuracion predeterminada es:

• Auth: localhost:9099
• Firestore: localhost:8080
• Storage: localhost:9199

Puedes sobrescribirla al inicializar Firebase:

const emulatorConfig: FirebaseEmulatorConfig = {
  auth: { host: "localhost", port: 9099 },
  firestore: { host: "localhost", port: 8080 },
  storage: { host: "localhost", port: 9199 },
};

firebaseService.init(firebaseOptions, true, emulatorConfig);