@roit/roit-data-firestore 1.2.42 → 1.2.44

package/README.md

@@ -159,6 +159,7 @@ Ref: [Firstore Operators](https://firebase.google.com/docs/firestore/query-data/
 | OrderBy Desc       | findByNameAndOrderByNameDesc       | .where('name', '==', value).orderBy("name", "desc")|
 | OrderBy Asc        | findByNameAndOrderByNameAsc        | .where('name', '==', value).orderBy("name", "asc")|
 | Limit              | findByNameAndLimit10               | .where('name', '==', value).limit(10)        |
+| OR Queries         | Manual query with `or` property    | Filter.or(...) - See OR Queries section     |
 
 #### Example
 
@@ -270,6 +271,112 @@ export class Repository1 extends BaseRepository<User> {
 }
 ```
 
+#### OR Queries
+
+The library supports OR queries using the `or` property within the query array. This allows you to create complex queries with multiple conditions using logical OR operations.
+
+##### Basic OR Query
+
+```
+findByStatusOrCategory(): Promise<Array<User>> {
+    return this.query({
+        query: [
+            {
+                or: [
+                    { field: 'status', operator: '==', value: 'active' },
+                    { field: 'status', operator: '==', value: 'pending' }
+                ]
+            }
+        ]
+    })
+}
+```
+
+##### OR with Simple Syntax
+
+```
+findByStatusOrCategory(): Promise<Array<User>> {
+    return this.query({
+        query: [
+            {
+                or: [
+                    { status: 'active' },
+                    { status: 'pending' }
+                ]
+            }
+        ]
+    })
+}
+```
+
+##### Combining AND and OR
+
+```
+findByCategoryAndStatusOrRating(): Promise<Array<User>> {
+    return this.query({
+        query: [
+            { field: 'category', operator: '==', value: 'electronics' },  // AND condition
+            {
+                or: [
+                    { field: 'price', operator: '>', value: 1000 },
+                    { field: 'rating', operator: '>', value: 4.5 }
+                ]
+            }
+        ]
+    })
+}
+```
+
+##### Multiple OR Groups
+
+```
+findByMultipleConditions(): Promise<Array<User>> {
+    return this.query({
+        query: [
+            { field: 'active', operator: '==', value: true },  // AND
+            {
+                or: [
+                    { field: 'price', operator: '>', value: 1000 },
+                    { field: 'popular', operator: '==', value: true }
+                ]
+            },
+            {
+                or: [
+                    { field: 'category', operator: 'in', value: ['electronics', 'books'] },
+                    { field: 'featured', operator: '==', value: true }
+                ]
+            }
+        ]
+    })
+}
+```
+
+##### OR with Different Operators
+
+```
+findByComplexConditions(): Promise<Array<User>> {
+    return this.query({
+        query: [
+            {
+                or: [
+                    { field: 'status', operator: '==', value: 'active' },
+                    { field: 'price', operator: '>', value: 100 },
+                    { field: 'tags', operator: 'array-contains', value: 'premium' },
+                    { field: 'category', operator: 'in', value: ['electronics', 'books'] }
+                ]
+            }
+        ]
+    })
+}
+```
+
+##### Limitations
+
+- Firestore limits OR queries to a maximum of 30 disjunctions
+- OR queries cannot be combined with `not-in` operators in the same query
+- Only one `not-in` or `!=` operator is allowed per query
+- Complex OR queries may require composite indexes in Firestore
+
 #### Paginated Query
 
 

package/dist/archive/ArchivePluginRegistry.d.ts

@@ -0,0 +1,78 @@
+import { IArchivePlugin } from './IArchivePlugin';
+/**
+ * Registry para o plugin de arquivamento
+ *
+ * Permite que aplicações registrem um plugin de archive (como firestore-archive)
+ * para habilitar funcionalidades de arquivamento de documentos.
+ *
+ * @example
+ * ```typescript
+ * import { registerArchivePlugin, getArchivePlugin } from '@roit/roit-data-firestore';
+ * import { createArchivePlugin } from 'firestore-archive';
+ *
+ * // No início da aplicação
+ * registerArchivePlugin(createArchivePlugin());
+ *
+ * // Em qualquer lugar da aplicação
+ * const plugin = getArchivePlugin();
+ * if (plugin.isEnabled()) {
+ *   const data = await plugin.getArchivedDocument({
+ *     collection: 'orders',
+ *     docId: 'abc123',
+ *     archivePath: 'gs://bucket/project/orders/YYYY/MM/DD/{ts}_abc123.json.gz',
+ *   });
+ * }
+ * ```
+ */
+declare class ArchivePluginRegistry {
+    private static instance;
+    private plugin;
+    private constructor();
+    static getInstance(): ArchivePluginRegistry;
+    /**
+     * Registra um plugin de archive
+     */
+    register(plugin: IArchivePlugin): void;
+    /**
+     * Retorna o plugin registrado (ou NoOp se nenhum foi registrado)
+     */
+    getPlugin(): IArchivePlugin;
+    /**
+     * Verifica se um plugin real foi registrado
+     */
+    hasPlugin(): boolean;
+    /**
+     * Reseta o registry (útil para testes)
+     */
+    reset(): void;
+}
+/**
+ * Registra um plugin de archive
+ * Deve ser chamado no início da aplicação, antes de usar repositórios
+ *
+ * @param plugin - Instância do plugin de archive
+ *
+ * @example
+ * ```typescript
+ * import { registerArchivePlugin } from '@roit/roit-data-firestore';
+ * import { createArchivePlugin } from 'firestore-archive';
+ *
+ * // No bootstrap da aplicação
+ * registerArchivePlugin(createArchivePlugin());
+ * ```
+ */
+export declare function registerArchivePlugin(plugin: IArchivePlugin): void;
+/**
+ * Retorna o plugin de archive registrado
+ * Se nenhum plugin foi registrado, retorna um plugin NoOp que desabilita todas as operações
+ */
+export declare function getArchivePlugin(): IArchivePlugin;
+/**
+ * Verifica se um plugin de archive foi registrado
+ */
+export declare function hasArchivePlugin(): boolean;
+/**
+ * Reseta o registry de plugins (útil para testes)
+ */
+export declare function resetArchivePlugin(): void;
+export { ArchivePluginRegistry };

package/dist/archive/ArchivePluginRegistry.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchivePluginRegistry = exports.resetArchivePlugin = exports.hasArchivePlugin = exports.getArchivePlugin = exports.registerArchivePlugin = void 0;
+/**
+ * Plugin NoOp - usado quando nenhum plugin de archive foi registrado
+ * Todas as operações retornam valores padrão indicando que archive está desabilitado
+ */
+class NoOpArchivePlugin {
+    isEnabled() {
+        return false;
+    }
+    isDocumentArchived(_doc) {
+        return false;
+    }
+    async getArchivedDocument(_params) {
+        return null;
+    }
+    async updateArchivedDocument(_params) {
+        return {
+            result: { success: false, message: 'Archive plugin not registered' },
+        };
+    }
+    async deleteArchivedDocument(_params) {
+        return { success: false, message: 'Archive plugin not registered' };
+    }
+    async invalidateCache(_collection, _docId) {
+        // No-op
+    }
+}
+/**
+ * Registry para o plugin de arquivamento
+ *
+ * Permite que aplicações registrem um plugin de archive (como firestore-archive)
+ * para habilitar funcionalidades de arquivamento de documentos.
+ *
+ * @example
+ * ```typescript
+ * import { registerArchivePlugin, getArchivePlugin } from '@roit/roit-data-firestore';
+ * import { createArchivePlugin } from 'firestore-archive';
+ *
+ * // No início da aplicação
+ * registerArchivePlugin(createArchivePlugin());
+ *
+ * // Em qualquer lugar da aplicação
+ * const plugin = getArchivePlugin();
+ * if (plugin.isEnabled()) {
+ *   const data = await plugin.getArchivedDocument({
+ *     collection: 'orders',
+ *     docId: 'abc123',
+ *     archivePath: 'gs://bucket/project/orders/YYYY/MM/DD/{ts}_abc123.json.gz',
+ *   });
+ * }
+ * ```
+ */
+class ArchivePluginRegistry {
+    constructor() {
+        // Inicializa com NoOp por padrão
+        this.plugin = new NoOpArchivePlugin();
+    }
+    static getInstance() {
+        if (!ArchivePluginRegistry.instance) {
+            ArchivePluginRegistry.instance = new ArchivePluginRegistry();
+        }
+        return ArchivePluginRegistry.instance;
+    }
+    /**
+     * Registra um plugin de archive
+     */
+    register(plugin) {
+        this.plugin = plugin;
+        console.log('[ArchivePluginRegistry] Archive plugin registered successfully');
+    }
+    /**
+     * Retorna o plugin registrado (ou NoOp se nenhum foi registrado)
+     */
+    getPlugin() {
+        return this.plugin;
+    }
+    /**
+     * Verifica se um plugin real foi registrado
+     */
+    hasPlugin() {
+        return !(this.plugin instanceof NoOpArchivePlugin);
+    }
+    /**
+     * Reseta o registry (útil para testes)
+     */
+    reset() {
+        this.plugin = new NoOpArchivePlugin();
+    }
+}
+exports.ArchivePluginRegistry = ArchivePluginRegistry;
+ArchivePluginRegistry.instance = null;
+// ========== Funções de conveniência ==========
+/**
+ * Registra um plugin de archive
+ * Deve ser chamado no início da aplicação, antes de usar repositórios
+ *
+ * @param plugin - Instância do plugin de archive
+ *
+ * @example
+ * ```typescript
+ * import { registerArchivePlugin } from '@roit/roit-data-firestore';
+ * import { createArchivePlugin } from 'firestore-archive';
+ *
+ * // No bootstrap da aplicação
+ * registerArchivePlugin(createArchivePlugin());
+ * ```
+ */
+function registerArchivePlugin(plugin) {
+    ArchivePluginRegistry.getInstance().register(plugin);
+}
+exports.registerArchivePlugin = registerArchivePlugin;
+/**
+ * Retorna o plugin de archive registrado
+ * Se nenhum plugin foi registrado, retorna um plugin NoOp que desabilita todas as operações
+ */
+function getArchivePlugin() {
+    return ArchivePluginRegistry.getInstance().getPlugin();
+}
+exports.getArchivePlugin = getArchivePlugin;
+/**
+ * Verifica se um plugin de archive foi registrado
+ */
+function hasArchivePlugin() {
+    return ArchivePluginRegistry.getInstance().hasPlugin();
+}
+exports.hasArchivePlugin = hasArchivePlugin;
+/**
+ * Reseta o registry de plugins (útil para testes)
+ */
+function resetArchivePlugin() {
+    ArchivePluginRegistry.getInstance().reset();
+}
+exports.resetArchivePlugin = resetArchivePlugin;

package/dist/archive/ArchiveService.d.ts

@@ -1,40 +1,90 @@
+/**
+ * Interface para opções de atualização de documento arquivado
+ */
+interface UpdateArchivedDocumentOptions {
+    /** Se true, remove o documento arquivado após a atualização (desarquivamento) */
+    unarchive?: boolean;
+}
+/**
+ * Resultado de operações de arquivamento
+ */
+interface ArchiveOperationResult {
+    success: boolean;
+    message?: string;
+    error?: Error;
+}
 export declare class ArchiveService {
     private static instance;
     private static readonly lock;
     private static isInitializing;
-    private storage;
-    private bucketName;
     private config;
-    private cacheResolver;
+    /** ProjectId do Firestore sendo arquivado (para organização de paths) */
     private projectId;
-    private firestore;
     private isInitialized;
+    private logger;
     /**
-    * Construtor privado para prevenir instanciação direta
-    */
+     * Construtor privado para prevenir instanciação direta
+     */
     private constructor();
     static getInstance(): Promise<ArchiveService>;
     private initialize;
     static resetInstance(): void;
     /**
      * Verifica se o arquivamento está habilitado
+     * Requer que o plugin firestore-archive esteja registrado
      */
     isEnabled(): boolean;
     /**
      * Verifica se um documento está arquivado
      */
     isDocumentArchived(documentData: any): boolean;
-    private pipeline;
-    /**
-     * Recupera documento arquivado em formato JSON
-     */
-    private retrieveJsonDocument;
     /**
      * Verifica se um documento está arquivado e recupera seus dados completos
      */
     getArchivedDocument(collectionName: string, doc: any): Promise<Record<string, any> | null>;
+    /**
+     * Atualiza um documento arquivado no Cloud Storage
+     * Usado quando um documento arquivado é atualizado no Firestore
+     *
+     * @param collectionName - Nome da collection
+     * @param docId - ID do documento
+     * @param newData - Novos dados a serem mesclados com o documento arquivado
+     * @param archivePath - Path completo do objeto no Storage, normalmente o `fbArchivePath` do stub.
+     * @param options - Opções de atualização
+     * @returns Resultado da operação e dados mesclados
+     */
+    updateArchivedDocument(collectionName: string, docId: string, newData: Record<string, any>, archivePath: string, options?: UpdateArchivedDocumentOptions): Promise<{
+        result: ArchiveOperationResult;
+        mergedData?: Record<string, any>;
+    }>;
+    /**
+     * Deleta um documento arquivado do Cloud Storage
+     * Usado quando um documento é permanentemente deletado ou restaurado
+     *
+     * @param collectionName - Nome da collection
+     * @param docId - ID do documento
+     * @param archivePath - Path completo do objeto no Storage, normalmente o `fbArchivePath` do stub.
+     * @returns Resultado da operação
+     */
+    deleteArchivedDocument(collectionName: string, docId: string, archivePath: string): Promise<ArchiveOperationResult>;
+    /**
+     * Recupera dados completos de um documento arquivado e o prepara para restauração
+     * Combina os dados do stub (Firestore) com os dados arquivados (Storage)
+     *
+     * @param collectionName - Nome da collection
+     * @param stubData - Dados do stub no Firestore (inclui fbArchivedAt)
+     * @returns Dados completos mesclados ou null se não encontrado
+     */
+    getCompleteArchivedDocument(collectionName: string, stubData: Record<string, any>): Promise<Record<string, any> | null>;
     /**
      * Limpa o cache de documentos arquivados
+     * Delega para o plugin firestore-archive
      */
     clearArchivedCache(collectionName?: string, docId?: string): Promise<void>;
+    /**
+     * Retorna o projectId do Firestore sendo arquivado
+     * (usado para organização de paths no Storage)
+     */
+    getProjectId(): string;
 }
+export {};