@roit/roit-data-firestore 1.2.46 → 1.2.47

package/dist/archive/ArchiveService.d.ts

@@ -1,12 +1,12 @@
 /**
- * Interface para opções de atualização de documento arquivado
+ * Interface for options to update an archived document
  */
 interface UpdateArchivedDocumentOptions {
-    /** Se true, remove o documento arquivado após a atualização (desarquivamento) */
+    /** If true, removes the archived document after the update (unarchiving) */
     unarchive?: boolean;
 }
 /**
- * Resultado de operações de arquivamento
+ * Result of archive operations
  */
 interface ArchiveOperationResult {
     success: boolean;
@@ -18,72 +18,79 @@ export declare class ArchiveService {
     private static readonly lock;
     private static isInitializing;
     private config;
-    /** ProjectId do Firestore sendo arquivado (para organização de paths) */
+    /** ProjectId of the Firestore being archived (for path organization) */
     private projectId;
     private isInitialized;
     private logger;
     /**
-     * Construtor privado para prevenir instanciação direta
+     * Private constructor to prevent direct instantiation
      */
     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
+     * Checks if the archive is enabled
+     * Requires the firestore-archive plugin to be registered
      */
     isEnabled(): boolean;
     /**
-     * Verifica se um documento está arquivado
+     * Checks if a document is archived
      */
     isDocumentArchived(documentData: any): boolean;
     /**
-     * Verifica se um documento está arquivado e recupera seus dados completos
+     * Returns the Cloud Storage path of the archived payload for a stub document.
+     *
+     * Marker-only: reads from `_rfa.archivePath`.
+     * Returns the trimmed string or undefined when missing/invalid.
+     */
+    static getArchivePath(documentData: any): string | undefined;
+    /**
+     * Checks if a document is archived and retrieves its complete data
      */
     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
+     * Updates an archived document in Cloud Storage
+     * Used when an archived document is updated in 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
+     * @param collectionName - Collection name
+     * @param docId - Document ID
+     * @param newData - New data to merge with the archived document
+     * @param archivePath - Full object path in Storage, usually the stub's `_rfa.archivePath`.
+     * @param options - Update options
+     * @returns Operation result and merged data
      */
     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
+     * Deletes an archived document from Cloud Storage
+     * Used when a document is permanently deleted or restored
      *
-     * @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
+     * @param collectionName - Collection name
+     * @param docId - Document ID
+     * @param archivePath - Full object path in Storage, usually the stub's `_rfa.archivePath`.
+     * @returns Operation result
      */
     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)
+     * Retrieves complete data of an archived document and prepares it for restoration
+     * Combines the stub data (Firestore) with the archived data (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
+     * @param collectionName - Collection name
+     * @param stubData - Stub data in Firestore (includes _rfa)
+     * @returns Complete merged data or null if not found
      */
     getCompleteArchivedDocument(collectionName: string, stubData: Record<string, any>): Promise<Record<string, any> | null>;
     /**
-     * Limpa o cache de documentos arquivados
-     * Delega para o plugin firestore-archive
+     * Clears the cache of archived documents
+     * Delegates to the firestore-archive plugin
      */
     clearArchivedCache(collectionName?: string, docId?: string): Promise<void>;
     /**
-     * Retorna o projectId do Firestore sendo arquivado
-     * (usado para organização de paths no Storage)
+     * Returns the projectId of the Firestore being archived
+     * (used for path organization in Storage)
      */
     getProjectId(): string;
 }

package/dist/archive/ArchiveService.js

@@ -4,7 +4,7 @@ exports.ArchiveService = void 0;
 const ArchiveConfig_1 = require("../config/ArchiveConfig");
 const index_1 = require("./index");
 /**
- * Logger interno para padronizar logs do ArchiveService
+ * Logger for ArchiveService
  */
 class ArchiveLogger {
     constructor(debug) {
@@ -30,23 +30,23 @@ class ArchiveLogger {
 }
 class ArchiveService {
     /**
-     * Construtor privado para prevenir instanciação direta
+     * Private constructor to prevent direct instantiation
      */
     constructor() {
         this.isInitialized = false;
-        // Construtor vazio - inicialização será feita em initialize()
+        // Empty constructor - initialization will be done in initialize()
     }
     static async getInstance() {
-        // Se já existe uma instância, retorna ela
+        // If an instance already exists, return it
         if (ArchiveService.instance && ArchiveService.instance.isInitialized) {
             return ArchiveService.instance;
         }
-        // Se está inicializando, aguarda
+        // If initializing, wait
         if (ArchiveService.isInitializing) {
             await ArchiveService.lock;
             return ArchiveService.instance;
         }
-        // Inicializa a instância
+        // Initialize the instance
         ArchiveService.isInitializing = true;
         try {
             if (!ArchiveService.instance) {
@@ -65,20 +65,20 @@ class ArchiveService {
         }
         this.config = ArchiveConfig_1.ArchiveConfig.getConfig();
         this.logger = new ArchiveLogger(this.config.debug);
-        // ProjectId do Firestore que está sendo arquivado (usado para paths no Storage)
+        // ProjectId of the Firestore being archived (used for paths in Storage)
         this.projectId = this.config.projectId;
         if (!this.projectId) {
-            this.logger.warn('projectId não configurado - usando variável de ambiente');
+            this.logger.warn('projectId not configured - using environment variable');
             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) {
-            this.logger.info('Arquivamento desabilitado via configuração');
+            this.logger.info('Archive disabled via configuration');
             this.isInitialized = true;
             return;
         }
         if (!(0, index_1.hasArchivePlugin)()) {
-            this.logger.warn('Plugin firestore-archive não registrado - arquivamento desabilitado');
+            this.logger.warn('Plugin firestore-archive not registered - archive disabled');
         }
         this.isInitialized = true;
     }
@@ -87,15 +87,15 @@ class ArchiveService {
         ArchiveService.isInitializing = false;
     }
     /**
-     * Verifica se o arquivamento está habilitado
-     * Requer que o plugin firestore-archive esteja registrado
+     * Checks if the archive is enabled
+     * Requires the firestore-archive plugin to be registered
      */
     isEnabled() {
-        // Arquivamento só funciona com plugin registrado
+        // Archive only works with registered plugin
         return this.config.enabled && (0, index_1.hasArchivePlugin)();
     }
     /**
-     * Verifica se um documento está arquivado
+     * Checks if a document is archived
      */
     isDocumentArchived(documentData) {
         if (!this.isEnabled()) {
@@ -104,20 +104,31 @@ class ArchiveService {
         return (0, index_1.getArchivePlugin)().isDocumentArchived(documentData);
     }
     /**
-     * Verifica se um documento está arquivado e recupera seus dados completos
+     * Returns the Cloud Storage path of the archived payload for a stub document.
+     *
+     * Marker-only: reads from `_rfa.archivePath`.
+     * Returns the trimmed string or undefined when missing/invalid.
+     */
+    static getArchivePath(documentData) {
+        const marker = (0, index_1.getArchiveMarker)(documentData);
+        if (!marker || typeof marker.archivePath !== 'string')
+            return undefined;
+        const trimmed = marker.archivePath.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    /**
+     * Checks if a document is archived and retrieves its complete data
      */
     async getArchivedDocument(collectionName, doc) {
         if (!this.isEnabled()) {
             return null;
         }
         const docId = doc.id;
-        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}`);
+        const archivePath = ArchiveService.getArchivePath(doc) || '';
+        if (!archivePath) {
+            throw new Error(`ArchiveService.getArchivedDocument: ${index_1.ARCHIVE_METADATA_FIELDS.ARCHIVE_PATH} is required. collection=${collectionName} docId=${docId}`);
         }
-        // Delega para plugin (isEnabled já garante que existe)
+        // Delegate to plugin (isEnabled already ensures it exists)
         return (0, index_1.getArchivePlugin)().getArchivedDocument({
             collection: collectionName,
             docId,
@@ -126,24 +137,24 @@ class ArchiveService {
         });
     }
     /**
-     * Atualiza um documento arquivado no Cloud Storage
-     * Usado quando um documento arquivado é atualizado no Firestore
+     * Updates an archived document in Cloud Storage
+     * Used when an archived document is updated in 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
+     * @param collectionName - Collection name
+     * @param docId - Document ID
+     * @param newData - New data to merge with the archived document
+     * @param archivePath - Full object path in Storage, usually the stub's `_rfa.archivePath`.
+     * @param options - Update options
+     * @returns Operation result and merged data
      */
     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}`);
+            throw new Error(`ArchiveService.updateArchivedDocument: ${index_1.ARCHIVE_METADATA_FIELDS.ARCHIVE_PATH} is required. collection=${collectionName} docId=${docId}`);
         }
-        // Delega para plugin (isEnabled já garante que existe)
+        // Delegate to plugin (isEnabled already ensures it exists)
         return (0, index_1.getArchivePlugin)().updateArchivedDocument({
             collection: collectionName,
             docId,
@@ -154,22 +165,22 @@ class ArchiveService {
         });
     }
     /**
-     * Deleta um documento arquivado do Cloud Storage
-     * Usado quando um documento é permanentemente deletado ou restaurado
+     * Deletes an archived document from Cloud Storage
+     * Used when a document is permanently deleted or restored
      *
-     * @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
+     * @param collectionName - Collection name
+     * @param docId - Document ID
+     * @param archivePath - Full object path in Storage, usually the stub's `_rfa.archivePath`.
+     * @returns Operation result
      */
     async deleteArchivedDocument(collectionName, docId, archivePath) {
         if (!this.isEnabled()) {
-            return { success: false, message: 'Arquivamento desabilitado ou plugin não registrado' };
+            return { success: false, message: 'Archive disabled or plugin not registered' };
         }
         if (!archivePath || typeof archivePath !== 'string' || archivePath.trim().length === 0) {
-            throw new Error(`ArchiveService.deleteArchivedDocument: fbArchivePath is required. collection=${collectionName} docId=${docId}`);
+            throw new Error(`ArchiveService.deleteArchivedDocument: ${index_1.ARCHIVE_METADATA_FIELDS.ARCHIVE_PATH} is required. collection=${collectionName} docId=${docId}`);
         }
-        // Delega para plugin (isEnabled já garante que existe)
+        // Delegate to plugin (isEnabled already ensures it exists)
         return (0, index_1.getArchivePlugin)().deleteArchivedDocument({
             collection: collectionName,
             docId,
@@ -178,12 +189,12 @@ class ArchiveService {
         });
     }
     /**
-     * Recupera dados completos de um documento arquivado e o prepara para restauração
-     * Combina os dados do stub (Firestore) com os dados arquivados (Storage)
+     * Retrieves complete data of an archived document and prepares it for restoration
+     * Combines the stub data (Firestore) with the archived data (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
+     * @param collectionName - Collection name
+     * @param stubData - Stub data in Firestore (includes _rfa)
+     * @returns Complete merged data or null if not found
      */
     async getCompleteArchivedDocument(collectionName, stubData) {
         if (!this.isDocumentArchived(stubData)) {
@@ -191,16 +202,16 @@ class ArchiveService {
         }
         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
+            this.logger.warn(`Archived data not found for document: ${collectionName}/${stubData.id}`);
+            return stubData; // Return stub if archived data is not found
         }
-        // Mesclar: dados do storage sobrescrevem o stub, exceto fbArchivedAt
-        const { fbArchivedAt } = stubData;
-        return { ...stubData, ...archivedData, fbArchivedAt };
+        // Merge: storage data overwrites the stub, except the marker _rfa
+        const marker = stubData?.[index_1.ARCHIVE_MARKER_KEY];
+        return { ...stubData, ...archivedData, [index_1.ARCHIVE_MARKER_KEY]: marker };
     }
     /**
-     * Limpa o cache de documentos arquivados
-     * Delega para o plugin firestore-archive
+     * Clears the cache of archived documents
+     * Delegates to the firestore-archive plugin
      */
     async clearArchivedCache(collectionName, docId) {
         if (!this.isEnabled()) {
@@ -209,8 +220,8 @@ class ArchiveService {
         await (0, index_1.getArchivePlugin)().invalidateCache(collectionName, docId);
     }
     /**
-     * Retorna o projectId do Firestore sendo arquivado
-     * (usado para organização de paths no Storage)
+     * Returns the projectId of the Firestore being archived
+     * (used for path organization in Storage)
      */
     getProjectId() {
         return this.projectId;

package/dist/archive/IArchivePlugin.d.ts

@@ -1,35 +1,35 @@
 /**
- * Interface para plugins de arquivamento
+ * Interface for archive plugins
  *
- * Esta interface define o contrato que plugins de archive devem implementar.
- * O plugin `firestore-archive` implementa esta interface.
+ * This interface defines the contract that archive plugins must implement.
+ * The `firestore-archive` plugin implements this interface.
  *
  * @example
  * ```typescript
  * import { registerArchivePlugin } from '@roit/roit-data-firestore';
  * import { createArchivePlugin } from 'firestore-archive';
  *
- * // Registrar o plugin no início da aplicação
+ * // Register the plugin at the beginning of the application
  * registerArchivePlugin(createArchivePlugin());
  * ```
  */
 export interface IArchivePlugin {
     /**
-     * Verifica se o arquivamento está habilitado
+     * Checks if the archive is enabled
      */
     isEnabled(): boolean;
     /**
-     * Verifica se um documento está arquivado (tem fbArchivedAt)
+     * Checks if a document is archived (has _rfa.archivedAt)
      */
     isDocumentArchived(doc: Record<string, unknown>): boolean;
     /**
-     * Recupera documento arquivado do Storage.
+     * Retrieves an archived document from Storage.
      *
-     * @param collection - Nome da collection
-     * @param docId - ID do documento
-     * @param archivePath - Path completo do objeto no Storage, normalmente o `fbArchivePath` do stub.
-     * @param projectId - ID do projeto (opcional)
-     * @returns Resultado da operação
+     * @param collection - Collection name
+     * @param docId - Document ID
+     * @param archivePath - Full object path in Storage, usually the stub's `_rfa.archivePath`.
+     * @param projectId - Project ID (optional)
+     * @returns Operation result
      */
     getArchivedDocument(params: {
         collection: string;
@@ -38,15 +38,15 @@ export interface IArchivePlugin {
         projectId?: string;
     }): Promise<Record<string, unknown> | null>;
     /**
-     * Atualiza documento arquivado (merge dados do Storage com novos dados)
+     * Updates an archived document (merge Storage data with new data)
      *
-     * @param collection - Nome da collection
-     * @param docId - ID do documento
-     * @param newData - Novos dados para mesclar
-     * @param options - Opções (unarchive: true para remover do Storage)
-     * @param projectId - ID do projeto (opcional)
-     * @param archivePath - Path completo do objeto no Storage, normalmente o `fbArchivePath` do stub. É obrigatório quando unarchive=true
-     * @returns Resultado com dados mesclados
+     * @param collection - Collection name
+     * @param docId - Document ID
+     * @param newData - New data to merge
+     * @param options - Options (unarchive: true to remove from Storage)
+     * @param projectId - Project ID (optional)
+     * @param archivePath - Full object path in Storage, usually the stub's `_rfa.archivePath`. Required when unarchive=true
+     * @returns Merged data
      */
     updateArchivedDocument(params: {
         collection: string;
@@ -66,12 +66,12 @@ export interface IArchivePlugin {
         mergedData?: Record<string, unknown>;
     }>;
     /**
-     * Deleta documento arquivado do Storage
+     * Deletes an archived document from Storage
      *
-     * @param collection - Nome da collection
-     * @param docId - ID do documento
-     * @param projectId - ID do projeto (opcional)
-     * @returns Resultado da operação
+     * @param collection - Collection name
+     * @param docId - Document ID
+     * @param projectId - Project ID (optional)
+     * @returns Operation result
      */
     deleteArchivedDocument(params: {
         collection: string;
@@ -84,19 +84,33 @@ export interface IArchivePlugin {
         error?: Error;
     }>;
     /**
-     * Invalida cache de documentos arquivados
+     * Invalidates the cache of archived documents
      *
-     * @param collection - Nome da collection (opcional)
-     * @param docId - ID do documento (opcional)
+     * @param collection - Collection name (optional)
+     * @param docId - Document ID (optional)
      */
     invalidateCache(collection?: string, docId?: string): Promise<void>;
 }
 /**
- * Campos de metadados de arquivamento no Firestore
+ * Archive marker key in Firestore (marker-only).
+ */
+export declare const ARCHIVE_MARKER_KEY: "_rfa";
+export type ArchiveMarker = {
+    archivedAt?: string;
+    archiveHash?: string;
+    archivePath?: string;
+    restoredAt?: string;
+    version?: number | string;
+};
+export declare function getArchiveMarker(doc: Record<string, unknown> | null | undefined): ArchiveMarker | null;
+/**
+ * Paths (dot-notation) for archive metadata in Firestore.
+ * Use these values in Firestore queries/updates; do not use for direct indexing in JS objects.
  */
 export declare const ARCHIVE_METADATA_FIELDS: {
-    readonly ARCHIVED_AT: "fbArchivedAt";
-    readonly ARCHIVE_HASH: "fbArchiveHash";
-    readonly ARCHIVE_PATH: "fbArchivePath";
-    readonly RESTORED_AT: "fbRestoredAt";
+    readonly ARCHIVED_AT: "_rfa.archivedAt";
+    readonly ARCHIVE_HASH: "_rfa.archiveHash";
+    readonly ARCHIVE_PATH: "_rfa.archivePath";
+    readonly RESTORED_AT: "_rfa.restoredAt";
+    readonly VERSION: "_rfa.version";
 };

package/dist/archive/IArchivePlugin.js

@@ -1,12 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ARCHIVE_METADATA_FIELDS = void 0;
+exports.ARCHIVE_METADATA_FIELDS = exports.getArchiveMarker = exports.ARCHIVE_MARKER_KEY = void 0;
 /**
- * Campos de metadados de arquivamento no Firestore
+ * Archive marker key in Firestore (marker-only).
+ */
+exports.ARCHIVE_MARKER_KEY = '_rfa';
+function getArchiveMarker(doc) {
+    if (!doc)
+        return null;
+    const marker = doc[exports.ARCHIVE_MARKER_KEY];
+    if (!marker || typeof marker !== 'object')
+        return null;
+    return marker;
+}
+exports.getArchiveMarker = getArchiveMarker;
+/**
+ * Paths (dot-notation) for archive metadata in Firestore.
+ * Use these values in Firestore queries/updates; do not use for direct indexing in JS objects.
  */
 exports.ARCHIVE_METADATA_FIELDS = {
-    ARCHIVED_AT: 'fbArchivedAt',
-    ARCHIVE_HASH: 'fbArchiveHash',
-    ARCHIVE_PATH: 'fbArchivePath',
-    RESTORED_AT: 'fbRestoredAt',
+    ARCHIVED_AT: `${exports.ARCHIVE_MARKER_KEY}.archivedAt`,
+    ARCHIVE_HASH: `${exports.ARCHIVE_MARKER_KEY}.archiveHash`,
+    ARCHIVE_PATH: `${exports.ARCHIVE_MARKER_KEY}.archivePath`,
+    RESTORED_AT: `${exports.ARCHIVE_MARKER_KEY}.restoredAt`,
+    VERSION: `${exports.ARCHIVE_MARKER_KEY}.version`,
 };

package/dist/archive/index.d.ts

@@ -1,2 +1,2 @@
-export { IArchivePlugin, ARCHIVE_METADATA_FIELDS } from './IArchivePlugin';
+export { IArchivePlugin, ARCHIVE_METADATA_FIELDS, ARCHIVE_MARKER_KEY, ArchiveMarker, getArchiveMarker, } from './IArchivePlugin';
 export { registerArchivePlugin, getArchivePlugin, hasArchivePlugin, resetArchivePlugin, ArchivePluginRegistry, } from './ArchivePluginRegistry';

package/dist/archive/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArchivePluginRegistry = exports.resetArchivePlugin = exports.hasArchivePlugin = exports.getArchivePlugin = exports.registerArchivePlugin = exports.ARCHIVE_METADATA_FIELDS = void 0;
+exports.ArchivePluginRegistry = exports.resetArchivePlugin = exports.hasArchivePlugin = exports.getArchivePlugin = exports.registerArchivePlugin = exports.getArchiveMarker = exports.ARCHIVE_MARKER_KEY = exports.ARCHIVE_METADATA_FIELDS = void 0;
 var IArchivePlugin_1 = require("./IArchivePlugin");
 Object.defineProperty(exports, "ARCHIVE_METADATA_FIELDS", { enumerable: true, get: function () { return IArchivePlugin_1.ARCHIVE_METADATA_FIELDS; } });
+Object.defineProperty(exports, "ARCHIVE_MARKER_KEY", { enumerable: true, get: function () { return IArchivePlugin_1.ARCHIVE_MARKER_KEY; } });
+Object.defineProperty(exports, "getArchiveMarker", { enumerable: true, get: function () { return IArchivePlugin_1.getArchiveMarker; } });
 var ArchivePluginRegistry_1 = require("./ArchivePluginRegistry");
 Object.defineProperty(exports, "registerArchivePlugin", { enumerable: true, get: function () { return ArchivePluginRegistry_1.registerArchivePlugin; } });
 Object.defineProperty(exports, "getArchivePlugin", { enumerable: true, get: function () { return ArchivePluginRegistry_1.getArchivePlugin; } });

package/dist/query/ManualQueryHelper.d.ts

@@ -4,7 +4,7 @@ export declare class ManualQueryHelper {
     static executeQueryManual(className: string, config: Config, queryRef?: boolean): Promise<any>;
     static executeQueryManualPaginated(className: string, config: Config): Promise<QueryResult>;
     /**
-     * Processa documentos arquivados, recuperando seus dados completos do Cloud Storage
+     * Processes archived documents, retrieving their complete data from Cloud Storage
      */
     private static processArchivedDocuments;
     static handleExecuteQueryManual(className: string, config: Config, options: Options, queryRef?: boolean): Promise<QueryResult>;

package/dist/query/ManualQueryHelper.js

@@ -7,7 +7,7 @@ const MQuery_1 = require("../model/MQuery");
 const QueryCreatorConfig_1 = require("./QueryCreatorConfig");
 const QueryPredicateFunctionTransform_1 = require("./QueryPredicateFunctionTransform");
 const ArchiveService_1 = require("../archive/ArchiveService");
-// import { ArchiveConfig } from "../config/ArchiveConfig";
+const archive_1 = require("../archive");
 class ManualQueryHelper {
     static async executeQueryManual(className, config, queryRef = false) {
         const result = await this.handleExecuteQueryManual(className, config, { showCount: false }, queryRef);
@@ -21,11 +21,11 @@ class ManualQueryHelper {
         return this.handleExecuteQueryManual(className, config, { showCount: true });
     }
     /**
-     * Processa documentos arquivados, recuperando seus dados completos do Cloud Storage
+     * Processes archived documents, retrieving their complete data from Cloud Storage
      */
     static async processArchivedDocuments(docs, collectionName) {
         const archiveService = await ArchiveService_1.ArchiveService.getInstance();
-        // Verifica se o arquivamento está habilitado
+        // Checks if the archive is enabled
         if (!archiveService.isEnabled()) {
             return docs;
         }
@@ -36,17 +36,18 @@ class ManualQueryHelper {
                 return null;
             }
             try {
-                // O ArchiveService agora gerencia o cache internamente baseado na configuração
+                // The ArchiveService now manages the cache internally based on the configuration
                 const archivedData = await archiveService.getArchivedDocument(collectionName, doc);
                 if (archivedData) {
-                    // Remove o flag de arquivamento e mescla os dados
-                    // const { fbArchivedAt, ...archivedDataWithoutFlag } = archivedData;
-                    return { ...doc, ...archivedData };
+                    // Merges the stub data with the archived data (the stub keeps _rfa)
+                    // Preserve the marker from stub to prevent archivedData from overwriting it
+                    const marker = doc?.[archive_1.ARCHIVE_MARKER_KEY];
+                    return { ...doc, ...archivedData, [archive_1.ARCHIVE_MARKER_KEY]: marker };
                 }
                 return doc;
             }
             catch (error) {
-                console.warn(`Erro ao recuperar documento arquivado ${doc.id}:`, error);
+                console.warn(`Error retrieving archived document ${doc.id}:`, error);
                 return doc;
             }
         });

package/dist/query/QueryPredicateFunctionTransform.js

@@ -82,7 +82,8 @@ class QueryPredicateFunctionTransform {
             aggregateCount: firestore_1.AggregateField.count,
             startTracer: Tracer_1.startTracer,
             archiveService: ArchiveService_1.ArchiveService.getInstance(),
-            ARCHIVE_FIELDS: archive_1.ARCHIVE_METADATA_FIELDS
+            ARCHIVE_FIELDS: archive_1.ARCHIVE_METADATA_FIELDS,
+            getArchivePath: ArchiveService_1.ArchiveService.getArchivePath
         };
         if (!options?.collection) {
             throw new Error(`Collection is required`);