valtech-components 2.0.795 → 2.0.797

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

@@ -1,685 +0,0 @@
-/**
- * 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,
-  getCountFromServer,
-  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';
-
-/**
- * Internal sentinel used to mark a collection path as global cross-app —
- * i.e. it should NOT be prefixed with `apps/{appId}/`.
- *
- * Apps consume this via `CollectionOptions.skipAppPrefix`; the sentinel
- * stays in `TypedCollection` and is stripped here before Firestore sees it.
- *
- * Format keeps it impossible to collide with a real Firestore path (`:` is
- * not allowed in collection segments).
- *
- * @internal
- */
-export const ABS_PATH_SENTINEL = '__abs__:';
-
-/**
- * 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).
-   *
-   * Si el path empieza con `ABS_PATH_SENTINEL` (`__abs__:`), se asume que el
-   * caller quiere un path global cross-app (ej. `users/{uid}/notifications` —
-   * el inbox global de notificaciones). El sentinel se strippea y el resto
-   * del path se pasa verbatim, sin prefijo `apps/{appId}/`.
-   *
-   * @internal
-   */
-  private prefixCollectionPath(collectionPath: string): string {
-    if (collectionPath.startsWith(ABS_PATH_SENTINEL)) {
-      return collectionPath.slice(ABS_PATH_SENTINEL.length);
-    }
-    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));
-  }
-
-  /**
-   * Cuenta documentos usando aggregation query del servidor.
-   * No descarga los documentos — mucho más eficiente para conteos y badges.
-   */
-  async countDocs(collectionPath: string, options?: QueryOptions): Promise<number> {
-    const prefixedPath = this.prefixCollectionPath(collectionPath);
-    const collectionRef = collection(this.firestore, prefixedPath);
-    const constraints = this.buildQueryConstraints(options);
-    const q = query(collectionRef, ...constraints);
-    const snapshot = await getCountFromServer(q);
-    return snapshot.data().count;
-  }
-
-  /**
-   * 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);
-
-    // Retornar optimísticamente sin segundo round-trip.
-    // serverTimestamp() resuelve en el servidor; usamos Date.now() localmente
-    // para evitar un getDoc() extra. El valor real llega en la próxima lectura.
-    const now = new Date();
-    return { id: docRef.id, ...data, createdAt: now, updatedAt: now } as T;
-  }
-
-  /**
-   * 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];
-  }
-}