valtech-components 2.0.687 → 2.0.689

package/src/lib/services/firebase/firestore.service.ts

@@ -0,0 +1,649 @@
+/**
+ * Firestore Service
+ *
+ * Servicio genérico para operaciones CRUD en Firestore.
+ * Soporta lecturas one-time, subscripciones real-time, paginación y queries complejas.
+ */
+
+import { inject, Injectable } from '@angular/core';
+import {
+  addDoc,
+  collection,
+  collectionData,
+  deleteDoc,
+  doc,
+  docData,
+  DocumentData,
+  DocumentReference,
+  DocumentSnapshot,
+  Firestore,
+  getDoc,
+  getDocs,
+  limit,
+  orderBy,
+  query,
+  QueryConstraint,
+  serverTimestamp,
+  setDoc,
+  startAfter,
+  startAt,
+  endBefore,
+  endAt,
+  Timestamp,
+  updateDoc,
+  where,
+  writeBatch,
+  increment,
+  arrayUnion,
+  arrayRemove,
+  FieldValue,
+} from '@angular/fire/firestore';
+import { map, Observable } from 'rxjs';
+
+import { VALTECH_FIREBASE_CONFIG } from './config';
+import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
+import { buildPath } from './utils/path-builder';
+
+/**
+ * Servicio para operaciones CRUD en Firestore.
+ *
+ * @example
+ * ```typescript
+ * interface User extends FirestoreDocument {
+ *   name: string;
+ *   email: string;
+ *   role: 'admin' | 'user';
+ * }
+ *
+ * @Component({...})
+ * export class UsersComponent {
+ *   private firestore = inject(FirestoreService);
+ *
+ *   // Lectura one-time
+ *   async loadUser(id: string) {
+ *     const user = await this.firestore.getDoc<User>('users', id);
+ *   }
+ *
+ *   // Subscripción real-time
+ *   users$ = this.firestore.collectionChanges<User>('users', {
+ *     where: [{ field: 'role', operator: '==', value: 'admin' }],
+ *     orderBy: [{ field: 'name', direction: 'asc' }]
+ *   });
+ *
+ *   // Crear documento
+ *   async createUser(data: Omit<User, 'id'>) {
+ *     const user = await this.firestore.addDoc<User>('users', data);
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class FirestoreService {
+  private config = inject(VALTECH_FIREBASE_CONFIG, { optional: true });
+
+  constructor(private firestore: Firestore) {}
+
+  /**
+   * Prefija el path de colección con el appId si está configurado.
+   * Si no hay appId, retorna el path sin modificar (backward compatible).
+   *
+   * @internal
+   */
+  private prefixCollectionPath(collectionPath: string): string {
+    if (!this.config?.appId) return collectionPath;
+    return `apps/${this.config.appId}/${collectionPath}`;
+  }
+
+  // ===========================================================================
+  // LECTURAS ONE-TIME (Promise)
+  // ===========================================================================
+
+  /**
+   * Obtiene un documento por ID (lectura única).
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param docId - ID del documento
+   * @returns Documento o null si no existe
+   *
+   * @example
+   * ```typescript
+   * const user = await firestoreService.getDoc<User>('users', 'abc123');
+   * if (user) {
+   *   console.log(user.name);
+   * }
+   * ```
+   */
+  async getDoc<T extends FirestoreDocument>(
+    collectionPath: string,
+    docId: string
+  ): Promise<T | null> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const docRef = doc(this.firestore, prefixedPath, docId);
+    const snapshot = await getDoc(docRef);
+
+    if (!snapshot.exists()) {
+      return null;
+    }
+
+    return this.mapDocument<T>(snapshot);
+  }
+
+  /**
+   * Obtiene múltiples documentos con opciones de query.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param options - Opciones de query (where, orderBy, limit)
+   * @returns Array de documentos
+   *
+   * @example
+   * ```typescript
+   * // Todos los usuarios activos ordenados por nombre
+   * const users = await firestoreService.getDocs<User>('users', {
+   *   where: [{ field: 'active', operator: '==', value: true }],
+   *   orderBy: [{ field: 'name', direction: 'asc' }],
+   *   limit: 50
+   * });
+   * ```
+   */
+  async getDocs<T extends FirestoreDocument>(
+    collectionPath: string,
+    options?: QueryOptions
+  ): Promise<T[]> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const collectionRef = collection(this.firestore, prefixedPath);
+    const constraints = this.buildQueryConstraints(options);
+    const q = query(collectionRef, ...constraints);
+    const snapshot = await getDocs(q);
+
+    return snapshot.docs.map((doc) => this.mapDocument<T>(doc));
+  }
+
+  /**
+   * Obtiene documentos con paginación basada en cursores.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param options - Opciones de query (debe incluir limit)
+   * @returns Resultado paginado con cursor para la siguiente página
+   *
+   * @example
+   * ```typescript
+   * // Primera página
+   * const page1 = await firestoreService.getPaginated<User>('users', {
+   *   orderBy: [{ field: 'createdAt', direction: 'desc' }],
+   *   limit: 10
+   * });
+   *
+   * // Siguiente página
+   * if (page1.hasMore) {
+   *   const page2 = await firestoreService.getPaginated<User>('users', {
+   *     orderBy: [{ field: 'createdAt', direction: 'desc' }],
+   *     limit: 10,
+   *     startAfter: page1.lastDoc
+   *   });
+   * }
+   * ```
+   */
+  async getPaginated<T extends FirestoreDocument>(
+    collectionPath: string,
+    options: QueryOptions & { limit: number }
+  ): Promise<PaginatedResult<T>> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const collectionRef = collection(this.firestore, prefixedPath);
+    const constraints = this.buildQueryConstraints(options);
+
+    // Pedir uno más para saber si hay más páginas
+    const q = query(collectionRef, ...constraints, limit(options.limit + 1));
+    const snapshot = await getDocs(q);
+
+    const docs = snapshot.docs;
+    const hasMore = docs.length > options.limit;
+
+    // Si hay más, remover el documento extra
+    const resultDocs = hasMore ? docs.slice(0, -1) : docs;
+    const lastDoc = resultDocs.length > 0 ? resultDocs[resultDocs.length - 1] : null;
+
+    return {
+      data: resultDocs.map((doc) => this.mapDocument<T>(doc)),
+      hasMore,
+      lastDoc,
+    };
+  }
+
+  /**
+   * Verifica si un documento existe.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param docId - ID del documento
+   * @returns true si el documento existe
+   */
+  async exists(collectionPath: string, docId: string): Promise<boolean> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const docRef = doc(this.firestore, prefixedPath, docId);
+    const snapshot = await getDoc(docRef);
+    return snapshot.exists();
+  }
+
+  // ===========================================================================
+  // SUBSCRIPCIONES REAL-TIME (Observable)
+  // ===========================================================================
+
+  /**
+   * Suscribe a cambios de un documento (real-time).
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param docId - ID del documento
+   * @returns Observable que emite cuando el documento cambia
+   *
+   * @example
+   * ```typescript
+   * // En el componente
+   * user$ = this.firestoreService.docChanges<User>('users', this.userId);
+   *
+   * // En el template
+   * @if (user$ | async; as user) {
+   *   <p>{{ user.name }}</p>
+   * }
+   * ```
+   */
+  docChanges<T extends FirestoreDocument>(
+    collectionPath: string,
+    docId: string
+  ): Observable<T | null> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const docRef = doc(this.firestore, prefixedPath, docId);
+    return docData(docRef, { idField: 'id' }).pipe(
+      map((data) => {
+        if (!data) return null;
+        return this.convertTimestamps(data as DocumentData) as T;
+      })
+    );
+  }
+
+  /**
+   * Suscribe a cambios de una colección (real-time).
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param options - Opciones de query
+   * @returns Observable que emite cuando la colección cambia
+   *
+   * @example
+   * ```typescript
+   * // Usuarios activos en tiempo real
+   * activeUsers$ = this.firestoreService.collectionChanges<User>('users', {
+   *   where: [{ field: 'status', operator: '==', value: 'online' }]
+   * });
+   * ```
+   */
+  collectionChanges<T extends FirestoreDocument>(
+    collectionPath: string,
+    options?: QueryOptions
+  ): Observable<T[]> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const collectionRef = collection(this.firestore, prefixedPath);
+    const constraints = this.buildQueryConstraints(options);
+    const q = query(collectionRef, ...constraints);
+
+    return collectionData(q, { idField: 'id' }).pipe(
+      map((docs) => docs.map((doc) => this.convertTimestamps(doc) as T))
+    );
+  }
+
+  // ===========================================================================
+  // ESCRITURA
+  // ===========================================================================
+
+  /**
+   * Agrega un documento con ID auto-generado.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param data - Datos del documento (sin id, createdAt, updatedAt)
+   * @returns Documento creado con su ID
+   *
+   * @example
+   * ```typescript
+   * const newUser = await firestoreService.addDoc<User>('users', {
+   *   name: 'John Doe',
+   *   email: 'john@example.com',
+   *   role: 'user'
+   * });
+   * console.log('Created user with ID:', newUser.id);
+   * ```
+   */
+  async addDoc<T extends FirestoreDocument>(
+    collectionPath: string,
+    data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>
+  ): Promise<T> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const collectionRef = collection(this.firestore, prefixedPath);
+    const timestamp = serverTimestamp();
+
+    const docData = {
+      ...data,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+
+    const docRef = await addDoc(collectionRef, docData);
+
+    // Obtener el documento creado para retornarlo con timestamps resueltos
+    const snapshot = await getDoc(docRef);
+    return this.mapDocument<T>(snapshot);
+  }
+
+  /**
+   * Crea o sobrescribe un documento con ID específico.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param docId - ID del documento
+   * @param data - Datos del documento
+   * @param options - Opciones (merge: true para merge en lugar de sobrescribir)
+   *
+   * @example
+   * ```typescript
+   * // Sobrescribir completamente
+   * await firestoreService.setDoc<User>('users', 'user123', userData);
+   *
+   * // Merge con datos existentes
+   * await firestoreService.setDoc<User>('users', 'user123', { name: 'New Name' }, { merge: true });
+   * ```
+   */
+  async setDoc<T extends FirestoreDocument>(
+    collectionPath: string,
+    docId: string,
+    data: Omit<T, 'id'>,
+    options?: { merge?: boolean }
+  ): Promise<void> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const docRef = doc(this.firestore, prefixedPath, docId);
+    const timestamp = serverTimestamp();
+
+    const docData = {
+      ...data,
+      updatedAt: timestamp,
+      ...(options?.merge ? {} : { createdAt: timestamp }),
+    };
+
+    await setDoc(docRef, docData, { merge: options?.merge ?? false });
+  }
+
+  /**
+   * Actualiza campos específicos de un documento.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param docId - ID del documento
+   * @param data - Campos a actualizar
+   *
+   * @example
+   * ```typescript
+   * await firestoreService.updateDoc<User>('users', 'user123', {
+   *   name: 'Updated Name',
+   *   lastLogin: new Date()
+   * });
+   * ```
+   */
+  async updateDoc<T extends FirestoreDocument>(
+    collectionPath: string,
+    docId: string,
+    data: Partial<Omit<T, 'id' | 'createdAt'>>
+  ): Promise<void> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const docRef = doc(this.firestore, prefixedPath, docId);
+
+    await updateDoc(docRef, {
+      ...data,
+      updatedAt: serverTimestamp(),
+    });
+  }
+
+  /**
+   * Elimina un documento.
+   *
+   * @param collectionPath - Ruta de la colección
+   * @param docId - ID del documento
+   *
+   * @example
+   * ```typescript
+   * await firestoreService.deleteDoc('users', 'user123');
+   * ```
+   */
+  async deleteDoc(collectionPath: string, docId: string): Promise<void> {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const docRef = doc(this.firestore, prefixedPath, docId);
+    await deleteDoc(docRef);
+  }
+
+  // ===========================================================================
+  // OPERACIONES EN LOTE
+  // ===========================================================================
+
+  /**
+   * Ejecuta múltiples operaciones de escritura de forma atómica.
+   *
+   * @param operations - Función que recibe el batch y agrega operaciones
+   *
+   * @example
+   * ```typescript
+   * await firestoreService.batch((batch) => {
+   *   batch.set('users/user1', { name: 'User 1' });
+   *   batch.update('users/user2', { status: 'inactive' });
+   *   batch.delete('users/user3');
+   * });
+   * ```
+   */
+  async batch(
+    operations: (batch: {
+      set: <T>(path: string, data: T) => void;
+      update: <T>(path: string, data: Partial<T>) => void;
+      delete: (path: string) => void;
+    }) => void
+  ): Promise<void> {
+    const batch = writeBatch(this.firestore);
+
+    const batchApi = {
+      set: <T>(path: string, data: T) => {
+        const [collectionPath, docId] = this.splitPath(path);
+        const prefixedPath = this.prefixCollectionPath(collectionPath);
+        const docRef = doc(this.firestore, prefixedPath, docId);
+        batch.set(docRef, {
+          ...data,
+          createdAt: serverTimestamp(),
+          updatedAt: serverTimestamp(),
+        } as DocumentData);
+      },
+      update: <T>(path: string, data: Partial<T>) => {
+        const [collectionPath, docId] = this.splitPath(path);
+        const prefixedPath = this.prefixCollectionPath(collectionPath);
+        const docRef = doc(this.firestore, prefixedPath, docId);
+        batch.update(docRef, {
+          ...data,
+          updatedAt: serverTimestamp(),
+        } as DocumentData);
+      },
+      delete: (path: string) => {
+        const [collectionPath, docId] = this.splitPath(path);
+        const prefixedPath = this.prefixCollectionPath(collectionPath);
+        const docRef = doc(this.firestore, prefixedPath, docId);
+        batch.delete(docRef);
+      },
+    };
+
+    operations(batchApi);
+    await batch.commit();
+  }
+
+  // ===========================================================================
+  // UTILIDADES
+  // ===========================================================================
+
+  /**
+   * Construye una ruta a partir de un template.
+   *
+   * @param template - Template con placeholders {param}
+   * @param params - Valores para los placeholders
+   * @returns Ruta construida
+   *
+   * @example
+   * ```typescript
+   * const path = firestoreService.buildPath('users/{userId}/documents/{docId}', {
+   *   userId: 'user123',
+   *   docId: 'doc456'
+   * });
+   * // => 'users/user123/documents/doc456'
+   * ```
+   */
+  buildPath(template: string, params: Record<string, string>): string {
+    return buildPath(template, params);
+  }
+
+  /**
+   * Genera un ID único para un documento (sin crearlo).
+   *
+   * @param collectionPath - Ruta de la colección
+   * @returns ID único generado por Firestore
+   */
+  generateId(collectionPath: string): string {
+    const prefixedPath = this.prefixCollectionPath(collectionPath);
+    const collectionRef = collection(this.firestore, prefixedPath);
+    return doc(collectionRef).id;
+  }
+
+  /**
+   * Retorna un valor de timestamp del servidor.
+   * Usar en campos de fecha para que Firestore asigne el timestamp.
+   */
+  serverTimestamp(): FieldValue {
+    return serverTimestamp();
+  }
+
+  /**
+   * Retorna un valor para agregar elementos a un array.
+   *
+   * @example
+   * ```typescript
+   * await firestoreService.updateDoc('users', 'user123', {
+   *   tags: firestoreService.arrayUnion('new-tag')
+   * });
+   * ```
+   */
+  arrayUnion(...elements: unknown[]): FieldValue {
+    return arrayUnion(...elements);
+  }
+
+  /**
+   * Retorna un valor para remover elementos de un array.
+   */
+  arrayRemove(...elements: unknown[]): FieldValue {
+    return arrayRemove(...elements);
+  }
+
+  /**
+   * Retorna un valor para incrementar un campo numérico.
+   *
+   * @example
+   * ```typescript
+   * await firestoreService.updateDoc('users', 'user123', {
+   *   loginCount: firestoreService.increment(1)
+   * });
+   * ```
+   */
+  increment(n: number): FieldValue {
+    return increment(n);
+  }
+
+  // ===========================================================================
+  // MÉTODOS PRIVADOS
+  // ===========================================================================
+
+  /**
+   * Construye los QueryConstraints a partir de QueryOptions
+   */
+  private buildQueryConstraints(options?: QueryOptions): QueryConstraint[] {
+    const constraints: QueryConstraint[] = [];
+
+    if (!options) return constraints;
+
+    // Where clauses
+    if (options.where) {
+      for (const clause of options.where) {
+        constraints.push(where(clause.field, clause.operator, clause.value));
+      }
+    }
+
+    // OrderBy clauses
+    if (options.orderBy) {
+      for (const clause of options.orderBy) {
+        constraints.push(orderBy(clause.field, clause.direction));
+      }
+    }
+
+    // Cursors para paginación
+    if (options.startAfter) {
+      constraints.push(startAfter(options.startAfter));
+    }
+    if (options.startAt) {
+      constraints.push(startAt(options.startAt));
+    }
+    if (options.endBefore) {
+      constraints.push(endBefore(options.endBefore));
+    }
+    if (options.endAt) {
+      constraints.push(endAt(options.endAt));
+    }
+
+    // Limit (se agrega al final)
+    if (options.limit) {
+      constraints.push(limit(options.limit));
+    }
+
+    return constraints;
+  }
+
+  /**
+   * Mapea un DocumentSnapshot a nuestro tipo
+   */
+  private mapDocument<T extends FirestoreDocument>(
+    snapshot: DocumentSnapshot<DocumentData>
+  ): T {
+    const data = snapshot.data();
+    if (!data) {
+      throw new Error('Documento no tiene datos');
+    }
+
+    return {
+      id: snapshot.id,
+      ...this.convertTimestamps(data),
+    } as T;
+  }
+
+  /**
+   * Convierte Timestamps de Firestore a Date de JavaScript
+   */
+  private convertTimestamps(data: DocumentData): DocumentData {
+    const result: DocumentData = {};
+
+    for (const [key, value] of Object.entries(data)) {
+      if (value instanceof Timestamp) {
+        result[key] = value.toDate();
+      } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+        result[key] = this.convertTimestamps(value);
+      } else {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Divide una ruta de documento en colección e ID
+   */
+  private splitPath(path: string): [string, string] {
+    const segments = path.split('/');
+    if (segments.length < 2 || segments.length % 2 !== 0) {
+      throw new Error(`Ruta de documento inválida: ${path}`);
+    }
+    const docId = segments.pop()!;
+    const collectionPath = segments.join('/');
+    return [collectionPath, docId];
+  }
+}