@roit/roit-data-firestore 1.2.43 → 1.2.45

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 {};

package/dist/archive/ArchiveService.js

@@ -1,40 +1,37 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArchiveService = void 0;
-const storage_1 = require("@google-cloud/storage");
-const zlib = __importStar(require("zlib"));
-const stream_1 = require("stream");
 const ArchiveConfig_1 = require("../config/ArchiveConfig");
-const CacheResolver_1 = require("../cache/CacheResolver");
-const CacheProviders_1 = require("../model/CacheProviders");
-const firestore_1 = require("@google-cloud/firestore");
+const index_1 = require("./index");
+/**
+ * Logger interno para padronizar logs do ArchiveService
+ */
+class ArchiveLogger {
+    constructor(debug) {
+        this.prefix = '[ArchiveServices]';
+        this.isDebug = debug;
+    }
+    debug(message, ...args) {
+        if (this.isDebug) {
+            console.debug(`${this.prefix} ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.isDebug) {
+            console.info(`${this.prefix} ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        console.warn(`${this.prefix} ${message}`, ...args);
+    }
+    error(message, ...args) {
+        console.error(`${this.prefix} ${message}`, ...args);
+    }
+}
 class ArchiveService {
     /**
-    * Construtor privado para prevenir instanciação direta
-    */
+     * Construtor privado para prevenir instanciação direta
+     */
     constructor() {
         this.isInitialized = false;
         // Construtor vazio - inicialização será feita em initialize()
@@ -67,33 +64,23 @@ class ArchiveService {
             return;
         }
         this.config = ArchiveConfig_1.ArchiveConfig.getConfig();
-        this.cacheResolver = CacheResolver_1.CacheResolver.getInstance();
+        this.logger = new ArchiveLogger(this.config.debug);
+        // ProjectId do Firestore que está sendo arquivado (usado para paths no Storage)
         this.projectId = this.config.projectId;
-        (0, ArchiveConfig_1.onDebugLog)(`Configuração: ${JSON.stringify(this.config)}`);
-        if (!this.firestore) {
-            this.firestore = new firestore_1.Firestore({
-                projectId: 'roit-intern-infra'
-            });
-        }
-        // REGISTRAR O ARCHIVESERVICE COMO REPOSITORY
-        this.cacheResolver.addRepository('ArchiveService', {
-            cacheExpiresInSeconds: 3600,
-            cacheProvider: CacheProviders_1.CacheProviders.REDIS_ARCHIVE
-        });
+        if (!this.projectId) {
+            this.logger.warn('projectId não configurado - usando variável de ambiente');
+            this.projectId = process.env.FIRESTORE_PROJECTID || process.env.GCP_PROJECT || '';
+        }
+        this.logger.debug(`Configuração: projectId=${this.projectId}, enabled=${this.config.enabled}`);
         if (!this.config.enabled) {
-            (0, ArchiveConfig_1.onDebugLog)('Arquivamento desabilitado');
+            this.logger.info('Arquivamento desabilitado via configuração');
+            this.isInitialized = true;
             return;
         }
-        else {
-            this.storage = new storage_1.Storage();
-            this.bucketName = this.config.bucketName;
-            if (!this.bucketName) {
-                (0, ArchiveConfig_1.onDebugWarn)('ArchiveService: bucket_name não configurado');
-            }
-            else {
-                (0, ArchiveConfig_1.onDebugLog)(`Bucket configurado: ${this.bucketName}`);
-            }
+        if (!(0, index_1.hasArchivePlugin)()) {
+            this.logger.warn('Plugin firestore-archive não registrado - arquivamento desabilitado');
         }
+        this.isInitialized = true;
     }
     static resetInstance() {
         ArchiveService.instance = null;
@@ -101,9 +88,11 @@ class ArchiveService {
     }
     /**
      * Verifica se o arquivamento está habilitado
+     * Requer que o plugin firestore-archive esteja registrado
      */
     isEnabled() {
-        return this.config.enabled;
+        // Arquivamento só funciona com plugin registrado
+        return this.config.enabled && (0, index_1.hasArchivePlugin)();
     }
     /**
      * Verifica se um documento está arquivado
@@ -112,43 +101,7 @@ class ArchiveService {
         if (!this.isEnabled()) {
             return false;
         }
-        return documentData && documentData.fbArchivedAt;
-    }
-    async pipeline(readStream, gunzip, writable) {
-        return new Promise((resolve, reject) => {
-            readStream.pipe(gunzip).pipe(writable);
-            writable.on('finish', resolve);
-            writable.on('error', reject);
-        });
-    }
-    /**
-     * Recupera documento arquivado em formato JSON
-     */
-    async retrieveJsonDocument(collectionName, docId) {
-        try {
-            const filePath = `${this.projectId}/${collectionName}/${docId}.json.gz`;
-            const bucket = this.storage.bucket(this.bucketName);
-            const file = bucket.file(filePath);
-            const [exists] = await file.exists();
-            if (!exists) {
-                return null;
-            }
-            const readStream = file.createReadStream();
-            const gunzip = zlib.createGunzip();
-            const chunks = [];
-            await this.pipeline(readStream, gunzip, new stream_1.Writable({
-                write(chunk, _enc, cb) {
-                    chunks.push(chunk);
-                    cb();
-                }
-            }));
-            const result = Buffer.concat(chunks).toString('utf-8');
-            return JSON.parse(result);
-        }
-        catch (error) {
-            console.log(`${ArchiveConfig_1.DEBUG_PREFIX} Erro ao recuperar documento JSON arquivado ${collectionName}/${docId}:`, error);
-            return null;
-        }
+        return (0, index_1.getArchivePlugin)().isDocumentArchived(documentData);
     }
     /**
      * Verifica se um documento está arquivado e recupera seus dados completos
@@ -157,45 +110,110 @@ class ArchiveService {
         if (!this.isEnabled()) {
             return null;
         }
-        if (!this.bucketName) {
-            console.warn(`${ArchiveConfig_1.DEBUG_PREFIX} ArchiveService: bucket_name não configurado, não é possível recuperar documentos arquivados`);
-            return null;
-        }
         const docId = doc.id;
-        // Verificar cache se habilitado
-        if (this.config.cache.enabled) {
-            const cacheKey = `archived_${collectionName}_${docId}`;
-            const cachedData = await this.cacheResolver.getCacheResult('ArchiveService', 'getArchivedDocument', cacheKey);
-            if (cachedData) {
-                (0, ArchiveConfig_1.onDebugLog)(`Cache hit para documento arquivado: ${collectionName}/${docId}`);
-                return cachedData;
-            }
-        }
-        try {
-            const archivedData = await this.retrieveJsonDocument(collectionName, docId);
-            if (archivedData) {
-                // Salvar no cache se habilitado
-                if (this.config.cache.enabled) {
-                    const cacheKey = `archived_${collectionName}_${docId}`;
-                    await this.cacheResolver.cacheResult('ArchiveService', 'getArchivedDocument', archivedData, cacheKey);
-                    (0, ArchiveConfig_1.onDebugLog)(`Documento arquivado cacheado: ${collectionName}/${docId}`);
-                }
-                return archivedData;
-            }
+        const archivePath = typeof doc?.[index_1.ARCHIVE_METADATA_FIELDS.ARCHIVE_PATH] === 'string'
+            ? doc[index_1.ARCHIVE_METADATA_FIELDS.ARCHIVE_PATH]
+            : '';
+        if (!archivePath || archivePath.trim().length === 0) {
+            throw new Error(`ArchiveService.getArchivedDocument: fbArchivePath is required. collection=${collectionName} docId=${docId}`);
+        }
+        // Delega para plugin (isEnabled já garante que existe)
+        return (0, index_1.getArchivePlugin)().getArchivedDocument({
+            collection: collectionName,
+            docId,
+            archivePath,
+            projectId: this.projectId,
+        });
+    }
+    /**
+     * 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
+     */
+    async updateArchivedDocument(collectionName, docId, newData, archivePath, options) {
+        if (!this.isEnabled()) {
+            return { result: { success: false, message: 'Arquivamento desabilitado ou plugin não registrado' } };
+        }
+        if (!archivePath || typeof archivePath !== 'string' || archivePath.trim().length === 0) {
+            throw new Error(`ArchiveService.updateArchivedDocument: fbArchivePath is required. collection=${collectionName} docId=${docId}`);
+        }
+        // Delega para plugin (isEnabled já garante que existe)
+        return (0, index_1.getArchivePlugin)().updateArchivedDocument({
+            collection: collectionName,
+            docId,
+            newData,
+            options,
+            projectId: this.projectId,
+            archivePath,
+        });
+    }
+    /**
+     * 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
+     */
+    async deleteArchivedDocument(collectionName, docId, archivePath) {
+        if (!this.isEnabled()) {
+            return { success: false, message: 'Arquivamento desabilitado ou plugin não registrado' };
         }
-        catch (error) {
-            console.warn(`${ArchiveConfig_1.DEBUG_PREFIX} Erro ao recuperar documento arquivado ${collectionName}/${docId}:`, error);
+        if (!archivePath || typeof archivePath !== 'string' || archivePath.trim().length === 0) {
+            throw new Error(`ArchiveService.deleteArchivedDocument: fbArchivePath is required. collection=${collectionName} docId=${docId}`);
         }
-        return null;
+        // Delega para plugin (isEnabled já garante que existe)
+        return (0, index_1.getArchivePlugin)().deleteArchivedDocument({
+            collection: collectionName,
+            docId,
+            projectId: this.projectId,
+            archivePath,
+        });
+    }
+    /**
+     * 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
+     */
+    async getCompleteArchivedDocument(collectionName, stubData) {
+        if (!this.isDocumentArchived(stubData)) {
+            return stubData;
+        }
+        const archivedData = await this.getArchivedDocument(collectionName, stubData);
+        if (!archivedData) {
+            this.logger.warn(`Dados arquivados não encontrados para documento: ${collectionName}/${stubData.id}`);
+            return stubData; // Retorna stub se não encontrar dados arquivados
+        }
+        // Mesclar: dados do storage sobrescrevem o stub, exceto fbArchivedAt
+        const { fbArchivedAt } = stubData;
+        return { ...stubData, ...archivedData, fbArchivedAt };
     }
     /**
      * Limpa o cache de documentos arquivados
+     * Delega para o plugin firestore-archive
      */
     async clearArchivedCache(collectionName, docId) {
-        if (!this.config.cache.enabled) {
+        if (!this.isEnabled()) {
             return;
         }
-        await this.cacheResolver.revokeArchiveCache(collectionName, docId);
+        await (0, index_1.getArchivePlugin)().invalidateCache(collectionName, docId);
+    }
+    /**
+     * Retorna o projectId do Firestore sendo arquivado
+     * (usado para organização de paths no Storage)
+     */
+    getProjectId() {
+        return this.projectId;
     }
 }
 exports.ArchiveService = ArchiveService;