valtech-components 2.0.451 → 2.0.453

package/lib/services/firebase/firestore-collection.d.ts

@@ -0,0 +1,175 @@
+import { Observable } from 'rxjs';
+import { FirestoreService } from './firestore.service';
+import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Opciones de configuración para una colección.
+ */
+export interface CollectionOptions {
+    /**
+     * Si true, usa soft delete (marca deletedAt en lugar de eliminar).
+     * Default: false
+     */
+    softDelete?: boolean;
+    /**
+     * Si true, maneja automáticamente createdAt/updatedAt.
+     * Default: true
+     */
+    timestamps?: boolean;
+}
+/**
+ * Referencia a una sub-colección tipada.
+ */
+export interface SubCollectionRef<T extends FirestoreDocument> {
+    getById(id: string): Promise<T | null>;
+    getAll(options?: QueryOptions): Promise<T[]>;
+    watch(id: string): Observable<T | null>;
+    watchAll(options?: QueryOptions): Observable<T[]>;
+    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Factory para crear instancias de colección tipadas.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class UsersService {
+ *   private users = inject(FirestoreCollectionFactory).create<User>('users');
+ *
+ *   getAll = () => this.users.getAll();
+ *   getById = (id: string) => this.users.getById(id);
+ *   create = (data: Omit<User, 'id'>) => this.users.create(data);
+ *
+ *   // Métodos personalizados
+ *   async getActiveUsers(): Promise<User[]> {
+ *     return this.users.query({
+ *       where: [{ field: 'active', operator: '==', value: true }]
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class FirestoreCollectionFactory {
+    private firestore;
+    constructor(firestore: FirestoreService);
+    /**
+     * Crea una instancia de colección tipada.
+     *
+     * @param collectionPath - Ruta de la colección en Firestore
+     * @param options - Opciones de configuración
+     * @returns Instancia de TypedCollection
+     */
+    create<T extends FirestoreDocument>(collectionPath: string, options?: CollectionOptions): TypedCollection<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FirestoreCollectionFactory, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FirestoreCollectionFactory>;
+}
+/**
+ * Colección tipada con métodos CRUD.
+ *
+ * NO usa inject() - recibe FirestoreService por constructor.
+ * Esto evita el error NG0203.
+ */
+export declare class TypedCollection<T extends FirestoreDocument> {
+    private firestore;
+    private collectionPath;
+    private readonly options;
+    constructor(firestore: FirestoreService, collectionPath: string, options?: CollectionOptions);
+    /**
+     * Obtiene un documento por ID.
+     */
+    getById(id: string): Promise<T | null>;
+    /**
+     * Obtiene todos los documentos de la colección.
+     */
+    getAll(options?: QueryOptions): Promise<T[]>;
+    /**
+     * Ejecuta una query personalizada.
+     */
+    query(options: QueryOptions): Promise<T[]>;
+    /**
+     * Obtiene documentos con paginación.
+     */
+    paginate(options: QueryOptions & {
+        limit: number;
+    }): Promise<PaginatedResult<T>>;
+    /**
+     * Obtiene el primer documento que coincida con la query.
+     */
+    getFirst(options?: QueryOptions): Promise<T | null>;
+    /**
+     * Cuenta los documentos que coinciden con la query.
+     * Nota: Esto carga todos los documentos, usar con cuidado en colecciones grandes.
+     */
+    count(options?: QueryOptions): Promise<number>;
+    /**
+     * Verifica si un documento existe.
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Suscribe a cambios de un documento.
+     */
+    watch(id: string): Observable<T | null>;
+    /**
+     * Suscribe a cambios de la colección.
+     */
+    watchAll(options?: QueryOptions): Observable<T[]>;
+    /**
+     * Suscribe a una query personalizada.
+     */
+    watchQuery(options: QueryOptions): Observable<T[]>;
+    /**
+     * Crea un nuevo documento con ID auto-generado.
+     */
+    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+    /**
+     * Crea un documento con ID específico.
+     */
+    createWithId(id: string, data: Omit<T, 'id'>): Promise<void>;
+    /**
+     * Actualiza campos de un documento.
+     */
+    update(id: string, data: Partial<Omit<T, 'id' | 'createdAt'>>): Promise<void>;
+    /**
+     * Elimina un documento.
+     * Si softDelete está habilitado, marca como eliminado en lugar de borrar.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Restaura un documento soft-deleted.
+     */
+    restore(id: string): Promise<void>;
+    /**
+     * Obtiene una referencia a una sub-colección.
+     *
+     * @example
+     * ```typescript
+     * // En UsersService
+     * getUserDocuments(userId: string) {
+     *   return this.users.subcollection<Document>(userId, 'documents');
+     * }
+     *
+     * // Uso
+     * const docs = await users.getUserDocuments('user123').getAll();
+     * ```
+     */
+    subcollection<S extends FirestoreDocument>(parentId: string, subcollectionName: string): SubCollectionRef<S>;
+    /**
+     * Aplica filtros por defecto a las queries.
+     */
+    private applyDefaultFilters;
+    /**
+     * Genera un nuevo ID sin crear el documento.
+     */
+    generateId(): string;
+    /**
+     * Obtiene la ruta de la colección.
+     */
+    getPath(): string;
+}
+/**
+ * @deprecated Use FirestoreCollectionFactory.create() instead.
+ * Type alias for backwards compatibility.
+ */
+export type FirestoreCollection<T extends FirestoreDocument> = TypedCollection<T>;

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

@@ -0,0 +1,304 @@
+import { Firestore, FieldValue } from '@angular/fire/firestore';
+import { Observable } from 'rxjs';
+import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
+import * as i0 from "@angular/core";
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+export declare class FirestoreService {
+    private firestore;
+    constructor(firestore: Firestore);
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    getDoc<T extends FirestoreDocument>(collectionPath: string, docId: string): Promise<T | null>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    getDocs<T extends FirestoreDocument>(collectionPath: string, options?: QueryOptions): Promise<T[]>;
+    /**
+     * 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
+     *   });
+     * }
+     * ```
+     */
+    getPaginated<T extends FirestoreDocument>(collectionPath: string, options: QueryOptions & {
+        limit: number;
+    }): Promise<PaginatedResult<T>>;
+    /**
+     * Verifica si un documento existe.
+     *
+     * @param collectionPath - Ruta de la colección
+     * @param docId - ID del documento
+     * @returns true si el documento existe
+     */
+    exists(collectionPath: string, docId: string): Promise<boolean>;
+    /**
+     * 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>;
+    /**
+     * 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[]>;
+    /**
+     * 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);
+     * ```
+     */
+    addDoc<T extends FirestoreDocument>(collectionPath: string, data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<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 });
+     * ```
+     */
+    setDoc<T extends FirestoreDocument>(collectionPath: string, docId: string, data: Omit<T, 'id'>, options?: {
+        merge?: boolean;
+    }): Promise<void>;
+    /**
+     * 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()
+     * });
+     * ```
+     */
+    updateDoc<T extends FirestoreDocument>(collectionPath: string, docId: string, data: Partial<Omit<T, 'id' | 'createdAt'>>): Promise<void>;
+    /**
+     * Elimina un documento.
+     *
+     * @param collectionPath - Ruta de la colección
+     * @param docId - ID del documento
+     *
+     * @example
+     * ```typescript
+     * await firestoreService.deleteDoc('users', 'user123');
+     * ```
+     */
+    deleteDoc(collectionPath: string, docId: string): Promise<void>;
+    /**
+     * 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');
+     * });
+     * ```
+     */
+    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>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Retorna un valor de timestamp del servidor.
+     * Usar en campos de fecha para que Firestore asigne el timestamp.
+     */
+    serverTimestamp(): FieldValue;
+    /**
+     * 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;
+    /**
+     * Retorna un valor para remover elementos de un array.
+     */
+    arrayRemove(...elements: unknown[]): FieldValue;
+    /**
+     * Retorna un valor para incrementar un campo numérico.
+     *
+     * @example
+     * ```typescript
+     * await firestoreService.updateDoc('users', 'user123', {
+     *   loginCount: firestoreService.increment(1)
+     * });
+     * ```
+     */
+    increment(n: number): FieldValue;
+    /**
+     * Construye los QueryConstraints a partir de QueryOptions
+     */
+    private buildQueryConstraints;
+    /**
+     * Mapea un DocumentSnapshot a nuestro tipo
+     */
+    private mapDocument;
+    /**
+     * Convierte Timestamps de Firestore a Date de JavaScript
+     */
+    private convertTimestamps;
+    /**
+     * Divide una ruta de documento en colección e ID
+     */
+    private splitPath;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FirestoreService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FirestoreService>;
+}

package/lib/services/firebase/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Firebase Services
+ *
+ * Servicios reutilizables para integración con Firebase.
+ *
+ * @example
+ * ```typescript
+ * // En main.ts
+ * import { provideValtechFirebase } from 'valtech-components';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechFirebase({
+ *       firebase: environment.firebase,
+ *       persistence: true,
+ *     }),
+ *   ],
+ * });
+ *
+ * // En componentes
+ * import { FirebaseService, FirestoreService } from 'valtech-components';
+ *
+ * @Component({...})
+ * export class MyComponent {
+ *   private firebase = inject(FirebaseService);
+ *   private firestore = inject(FirestoreService);
+ * }
+ * ```
+ */
+export * from './types';
+export { VALTECH_FIREBASE_CONFIG, hasEmulators, provideValtechFirebase } from './config';
+export { APP_IDS, FIREBASE_PROJECTS, SHARED_EMULATOR_CONFIG, collections, createFirebaseConfig, isEmulatorMode, storagePaths, type AppId, type CreateFirebaseConfigOptions, } from './shared-config';
+export { FirebaseService } from './firebase.service';
+export { FirestoreService } from './firestore.service';
+export { CollectionOptions, FirestoreCollection, FirestoreCollectionFactory, SubCollectionRef, TypedCollection, } from './firestore-collection';
+export { QueryBuilder, query } from './utils/query-builder';
+export { buildPath, extractPathParams, getCollectionPath, getDocumentId, isCollectionPath, isDocumentPath, isValidPath, joinPath, } from './utils/path-builder';
+export { StorageService } from './storage.service';
+export { MessagingService } from './messaging.service';