Documentation 7 min read

Easy Firebase Manager

firebase

Published: April 21, 2025

Introdução

O Easy Firebase Manager é uma biblioteca JavaScript que gerencia os serviços do Firebase – incluindo Autenticação, Firestore, Realtime Database e Storage – utilizando os módulos Compat do Firebase v9+. A biblioteca incorpora recursos avançados como:

  • Cache local (via IndexedDB) com expiração configurável.
  • Sistema de eventos personalizados para monitorar operações.
  • Logs de auditoria para rastreamento e análise das operações realizadas.
  • Retry logic para lidar com erros transitórios (como falhas de rede).
  • Refatoração e correções, incluindo melhorias de serialização no IndexedDB e refinamento do RTDB increment logging.

Esta versão foi corrigida, refatorada e aprimorada com base no feedback dos usuários.

Principais Funcionalidades

  • Gerenciamento de Autenticação: Métodos para login, signup, envio de email de redefinição e confirmação.
  • FireStore: Criação, leitura, atualização e deleção de documentos; listagem com filtros, ordenação e paginação; operações em lote e clonagem de registros.
  • Realtime Database: Operações de set, get, update e remove; suporte a transações com operações atômicas (incremento e decremento).
  • Firebase Storage: Upload, download e deleção de arquivos.
  • Caching Local: Uso de IndexedDB para armazenar dados lidos do Firestore e RTDB para melhorar a performance.
  • Eventos Personalizados: Permite escutar eventos como auth, fsCreate, fsRead, fsRealtimeUpdate, rtdbSet, uploadProgress e muitos outros.
  • Logs de Auditoria: Cada operação crítica é registrada com detalhes e timestamp, ideal para depuração e monitoramento.
  • Retry Logic: Operações falhas são automaticamente reexecutadas (com backoff exponencial) caso se trate de erros do tipo rede ou indisponibilidade.
  • Persistência de Dados de Analytics: As estatísticas e os logs podem ser salvos em IndexedDB para persistência entre sessões.

Requisitos

Para usar o Easy Firebase Manager, é necessário:

  • Ter os scripts do Firebase Compat (v9+) carregados previamente:
    • firebase-app-compat.js
    • firebase-auth-compat.js
    • firebase-firestore-compat.js
    • firebase-database-compat.js
    • firebase-storage-compat.js
  • Um projeto Firebase configurado com as credenciais apropriadas.

Instalação e Download

  1. Inclua os scripts do Firebase:

    Por exemplo, no seu HTML (antes do fechamento da tag </body>), insira:

<script src="https://www.gstatic.com/firebasejs/9.6.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.6.1/firebase-auth-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.6.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.6.1/firebase-database-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.6.1/firebase-storage-compat.js"></script>

  1. Inclua o script do Easy Firebase Manager:

    Adicione a linha abaixo (ou utilize o link para fazer o download):

<script src="https://cdn.alphasystem.dev/plugins/easy-firebase-manager/latest/script-min.js"></script>

Configuração

Para iniciar, configure a instância passando seu objeto de configuração do Firebase e as opções desejadas. Por exemplo:

// Exemplo de inicialização básica:
const firebaseConfig = {
	apiKey: "YOUR_API_KEY",
	authDomain: "YOUR_AUTH_DOMAIN",
	projectId: "YOUR_PROJECT_ID",
	databaseURL: "YOUR_RTDB_URL",
	storageBucket: "YOUR_STORAGE_BUCKET",
	messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
	appId: "YOUR_APP_ID"
};

const firebaseManager = new FirebaseManager(firebaseConfig, {
	defaultCollectionPath: "users",          // Coleção padrão para Firestore
	defaultRtdbPath: "appData",              // Caminho padrão para Realtime Database
	cacheEnabled: true,                      // Habilita o cache para Firestore e RTDB
	cacheExpirationMinutes: 60,              // Cache expira após 60 minutos
	persistenceEnabled: true,                // Persiste logs de auditoria e analytics
	retryAttempts: 3,                        // Número de tentativas de retry
	retryBackoff: 300                        // Backoff inicial em milissegundos
});

Uso e Integração

Autenticação

Utilize os métodos de autenticação para gerenciar o login, o signup e outras funcionalidades:

// Fazer login com email e senha:
firebaseManager.login("user@example.com", "password123")
	.then(userCredential => {
		console.log("Usuário autenticado:", userCredential.user);
	})
	.catch(error => {
		console.error("Erro no login:", error);
	});

// Realizar signup e criar opcionalmente um documento de perfil:
firebaseManager.signup("newuser@example.com", "password123", { name: "New User" }, "users")
	.then(userCredential => {
		console.log("Usuário registrado:", userCredential.user);
	})
	.catch(error => {
		console.error("Erro no signup:", error);
	});

Operações no Firestore

Criar, Ler, Atualizar e Deletar Documentos

// Criar um documento na coleção "users":
firebaseManager.create({ name: "Alice", age: 30 }, "users")
	.then(doc => {
		console.log("Documento criado:", doc);
	})
	.catch(err => {
		console.error("Erro ao criar documento:", err);
	});

// Ler um documento específico:
firebaseManager.read("DOCUMENT_ID", "users")
	.then(doc => {
		console.log("Documento lido:", doc);
	})
	.catch(err => {
		console.error("Erro na leitura:", err);
	});

// Atualizar um documento:
firebaseManager.update("DOCUMENT_ID", { age: 31 }, "users")
	.then(() => {
		console.log("Documento atualizado com sucesso.");
	})
	.catch(err => {
		console.error("Erro ao atualizar documento:", err);
	});

// Deletar um documento:
firebaseManager.delete("DOCUMENT_ID", "users")
	.then(() => {
		console.log("Documento deletado.");
	})
	.catch(err => {
		console.error("Erro ao deletar documento:", err);
	});

Operações em Lote e Clonagem

// Executar operações em lote:
const operations = [
	{ type: "set", path: "users/user1", data: { name: "User One" } },
	{ type: "update", path: "users/user2", data: { age: 25 } },
	{ type: "delete", path: "users/user3" }
];

firebaseManager.batchWrite(operations)
	.then(() => {
		console.log("Batch write realizado com sucesso.");
	})
	.catch(err => {
		console.error("Erro no batch write:", err);
	});

// Clonar um documento:
firebaseManager.cloneRecord("DOCUMENT_ID", "users")
	.then(newDoc => {
		console.log("Documento clonado:", newDoc);
	})
	.catch(err => {
		console.error("Erro ao clonar documento:", err);
	});

Listar e Acompanhar Atualizações em Tempo Real

// Listar documentos com filtros, ordenação e limite:
firebaseManager.list({
	filter: [["age", ">", 25]],
	sort: [["name", "asc"]],
	limit: 10
}, "users")
	.then(docs => {
		console.log("Documentos listados:", docs);
	})
	.catch(err => {
		console.error("Erro na listagem:", err);
	});

// Assinar atualizações em tempo real para um documento:
firebaseManager.readWithAutoUpdate("DOCUMENT_ID", "users", (updatedDoc) => {
	console.log("Atualização em tempo real:", updatedDoc);
});

// Assinar atualizações em tempo real para uma query (recupere uma função de desinscrição):
const unsubscribe = await firebaseManager.listWithAutoUpdate({
	filter: [["age", "<", 30]],
	sort: [["name", "desc"]],
	limit: 5
}, "users", (docs) => {
	console.log("Atualização da lista em tempo real:", docs);
});

// Para cancelar a assinatura, execute:
unsubscribe();

Realtime Database (RTDB) Operations

Set, Get, Update, Remove e Transações

// Definir dados em um caminho do RTDB:
firebaseManager.rtdbSet("users/user1/profile", { name: "Alice" }, "rtdb")
	.then(() => {
		console.log("Dados gravados no RTDB.");
	})
	.catch(err => {
		console.error("Erro no RTDB set:", err);
	});

// Obter dados de um caminho do RTDB:
firebaseManager.rtdbGet("users/user1/profile", "rtdb")
	.then(data => {
		console.log("Dados do RTDB:", data);
	})
	.catch(err => {
		console.error("Erro no RTDB get:", err);
	});

// Atualizar dados no RTDB:
firebaseManager.rtdbUpdate("users/user1/profile", { age: 28 }, "rtdb")
	.then(() => {
		console.log("Dados atualizados no RTDB.");
	})
	.catch(err => {
		console.error("Erro no RTDB update:", err);
	});

// Remover dados do RTDB:
firebaseManager.rtdbRemove("users/user1/profile", "rtdb")
	.then(() => {
		console.log("Dados removidos do RTDB.");
	})
	.catch(err => {
		console.error("Erro no RTDB remove:", err);
	});

// Incrementar um valor numericamente (transação atômica):
firebaseManager.rtdbIncrement("counters/likes", 1, "rtdb")
	.then(result => {
		console.log("Resultado do incremento:", result);
	})
	.catch(err => {
		console.error("Erro no RTDB increment:", err);
	});

Firebase Storage Operations

// Fazer upload de um arquivo:
const fileInput = document.querySelector("#fileInput");
fileInput.addEventListener("change", async (event) => {
	const file = event.target.files[0];
	try {
		const uploadResult = await firebaseManager.uploadFile(file, "uploads/profile.jpg");
		console.log("File uploaded. Download URL:", uploadResult.downloadURL);
	} catch (err) {
		console.error("Erro no upload de arquivo:", err);
	}
});

// Obter download URL de um arquivo:
firebaseManager.getDownloadURL("uploads/profile.jpg")
	.then(url => {
		console.log("Download URL:", url);
	})
	.catch(err => {
		console.error("Erro ao obter download URL:", err);
	});

// Deletar um arquivo do Storage:
firebaseManager.deleteFileFromStorage("uploads/profile.jpg")
	.then(() => {
		console.log("Arquivo deletado do Storage.");
	})
	.catch(err => {
		console.error("Erro ao deletar arquivo do Storage:", err);
	});

Exportação e Importação de Dados

Firestore

// Exportar documentos do Firestore para JSON, CSV ou XML:
firebaseManager.downloadAsJSON("users")
	.then(() => {
		console.log("Exportação JSON iniciada.");
	})
	.catch(err => {
		console.error("Erro na exportação JSON:", err);
	});

firebaseManager.downloadAsCSV("users")
	.then(() => {
		console.log("Exportação CSV iniciada.");
	})
	.catch(err => {
		console.error("Erro na exportação CSV:", err);
	});

firebaseManager.downloadAsXML("users")
	.then(() => {
		console.log("Exportação XML iniciada.");
	})
	.catch(err => {
		console.error("Erro na exportação XML:", err);
	});

// Importar documentos a partir de uma string JSON:
const jsonData = '[{"id":"user1","name":"Alice","age":30},{"id":"user2","name":"Bob","age":25}]';
firebaseManager.importFromJSON(jsonData, "users")
	.then(() => {
		console.log("Importação JSON concluída.");
	})
	.catch(err => {
		console.error("Erro na importação JSON:", err);
	});

Realtime Database

// Exportar dados do RTDB para JSON:
firebaseManager.exportRtdbToJSON("users/user1", "rtdb")
	.then(jsonString => {
		console.log("Dados RTDB exportados:", jsonString);
	})
	.catch(err => {
		console.error("Erro na exportação RTDB:", err);
	});

// Importar dados para o RTDB a partir de JSON:
const rtdbJsonData = '{"name": "Alice", "age": 30}';
firebaseManager.importRtdbFromJSON("users/user1", rtdbJsonData, "rtdb")
	.then(() => {
		console.log("Importação RTDB concluída.");
	})
	.catch(err => {
		console.error("Erro na importação RTDB:", err);
	});

Cache, Analytics e Logs de Auditoria

// Limpar o cache de dados (Firestore e RTDB)
firebaseManager.clearCache()
	.then(() => {
		console.log("Cache limpo.");
	})
	.catch(err => {
		console.error("Erro ao limpar cache:", err);
	});

// Obter dados de analytics e logs de auditoria
console.log("Analytics:", firebaseManager.getAnalytics());
console.log("Audit Logs:", firebaseManager.getAuditLogs());

Resolução de Problemas

  • Firebase SDK não carregado: Certifique-se de que os scripts do Firebase Compat sejam incluídos antes do Easy Firebase Manager.
  • Serviço Indisponível: Se um serviço (por exemplo, Firestore, RTDB, Storage) não estiver disponível, verifique se o respectivo módulo foi carregado.
  • Erros de Retentativa: O sistema utiliza retries com backoff exponencial para erros de rede. Se uma operação falhar repetidamente, revise sua conexão e as credenciais.
  • Cache e Persistência: Caso os dados em cache não estejam sendo atualizados, verifique se a opção cacheEnabled está ativada e se o IndexedDB está funcionando corretamente.
  • Formato dos Dados: Em operações de importação/exportação (JSON, CSV, XML), confirme que os dados estejam no formato esperado.
  • Realtime Subscriptions: Certifique-se de passar callbacks válidos para métodos como readWithAutoUpdate e listWithAutoUpdate.
  • Logs de Auditoria: Examine os logs de auditoria (via getAuditLogs()) para entender melhor as operações realizadas e eventuais falhas.