Easy PocketBase Manager - Alpha System Plugins

Introdução

O Easy PocketBase Manager é uma biblioteca JavaScript robusta projetada para simplificar a interação com o PocketBase. Ele fornece uma interface unificada para realizar operações de autenticação, gerenciamento de dados, manipulação de arquivos, controle de roles e muito mais. Além disso, o Easy PocketBase Manager incorpora funcionalidades avançadas como gerenciamento de eventos personalizados, análise de operações realizadas, cache de dados utilizando o IndexedDB e persistência de dados.

Principais funcionalidades do Easy PocketBase Manager:

Gerenciamento de autenticação de usuários (login, signup, logout, logoutAndClear, verificação de email, recuperação de senha).
Operações CRUD (Create, Read, Update, Delete) simplificadas para coleções do PocketBase.
Operações em lote para criação, atualização e exclusão de múltiplos registros.
Manipulação de arquivos, incluindo upload de um ou múltiplos arquivos e download.
Gerenciamento de roles e permissões de usuários.
Emissão e escuta de eventos personalizados para monitorar ações específicas.
Análise detalhada das operações realizadas e uso de recursos.
Exportação e importação de dados em formato JSON, CSV e XML para facilitar migrações e backups.
Sincronização de dados entre diferentes instâncias do PocketBaseManager.
Cache de dados utilizando IndexedDB para melhorar o desempenho e reduzir a necessidade de requisições ao servidor.
Persistência de dados como logs de auditoria, sessões e análises utilizando IndexedDB.
Facilidade de integração com projetos existentes graças a uma API intuitiva e documentação detalhada.

Características Principais

Gerenciamento de Autenticação: Facilita o processo de login, signup, logout, logoutAndClear, verificação de email e recuperação de senha.
Operações CRUD Simplificadas: Métodos intuitivos para criar, ler, atualizar e deletar registros em coleções do PocketBase.
Operações em Lote: Suporte para criação, atualização e exclusão de múltiplos registros de uma só vez, otimizando o desempenho.
Manipulação de Arquivos: Upload de um ou múltiplos arquivos e download de arquivos associados a registros, com gerenciamento eficiente de armazenamento.
Gerenciamento de Roles: Atribuição e recuperação de roles para usuários, permitindo controle granular de permissões.
Eventos Personalizados: Emissão de eventos como 'auth', 'signup', 'create', 'update', 'delete', 'list', 'batchCreate', 'batchUpdate', 'batchDelete', 'fileUploaded', 'roleAssigned', 'rolesFetched', 'import', 'sync', entre outros, permitindo integração com outras partes da aplicação.
Análise de Operações: Monitoramento de operações realizadas, incluindo contagem de operações e uso de bytes.
Exportação e Importação de Dados: Métodos para exportar dados para JSON, CSV e XML e importar dados a partir desses formatos, facilitando backups e migrações.
Sincronização de Dados: Sincronização de dados entre diferentes instâncias do PocketBaseManager para manter a consistência.
Cache de Dados: Utiliza o IndexedDB para armazenar registros em cache, melhorando o desempenho e reduzindo a necessidade de requisições frequentes ao servidor.
Persistência de Dados: Armazena logs de auditoria, sessões e análises utilizando IndexedDB para garantir a persistência dos dados.
Facilidade de Integração: API intuitiva e documentação detalhada que facilitam a integração com projetos existentes.

Instalação

Para instalar o Easy PocketBase Manager, siga os passos abaixo:

Passo a Passo

Inclua o Script do PocketBase: Adicione o script do PocketBase no seu HTML antes do fechamento da tag </body>:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pocketbase/0.25.0/pocketbase.umd.js"></script>

Inclua o Script do PocketBase Manager: Adicione o script do PocketBase Manager após o script do PocketBase:

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

Inicialização Básica: Inicialize o PocketBase Manager com as configurações padrão:

// Inicializa o PocketBase Manager com as configurações padrão
// Certifique-se de que 'PocketBase' foi carregado antes (via script do PocketBase)

const pbManager = new PocketBaseManager({
  baseUrl: 'http://127.0.0.1:8090', // URL base do PocketBase
  collection: 'users' // Coleção padrão a ser utilizada
});

Configuração Avançada (Opcional): Personalize as opções conforme necessário:

// Exemplo de configuração avançada
// A classe PocketBaseManager se encarrega de instanciar o PocketBase internamente.

const pbManager = new PocketBaseManager({
  baseUrl: 'https://meuservidor.com',
  collection: 'clientes',
  cacheEnabled: true, // Habilita o cache de dados (IndexedDB)
  cacheExpirationMinutes: 120, // Define a expiração do cache para 120 minutos
  syncIntervalMinutes: 15, // Define o intervalo de sincronização para 15 minutos
  persistenceEnabled: true // Habilita a persistência de dados
  // Outras opções de configuração podem ser adicionadas conforme necessário
});

Configuração

O Easy PocketBase Manager oferece várias opções de configuração para personalizar seu comportamento e funcionalidades. As configurações padrão podem ser sobrescritas pelo usuário através do objeto de opções passado na inicialização do PocketBaseManager. A seguir, detalhamos as principais opções disponíveis:

baseUrl: (String) URL base do servidor PocketBase. Padrão: 'http://127.0.0.1:8090'.
collection: (String) Nome da coleção padrão a ser utilizada nas operações CRUD. Padrão: null.
cacheEnabled: (Boolean) Habilita ou desabilita o cache de dados utilizando IndexedDB. Padrão: true.
cacheExpirationMinutes: (Number) Define o tempo de expiração do cache em minutos. Padrão: 60.
syncIntervalMinutes: (Number) Define o intervalo de sincronização de dados em minutos. Padrão: 10.
persistenceEnabled: (Boolean) Habilita ou desabilita a persistência de dados (logs de auditoria, sessões e análises) utilizando IndexedDB. Padrão: true.

Nota: Certifique-se de que o servidor PocketBase está corretamente configurado e acessível através da baseUrl fornecida. Também verifique se o script do PocketBase (pocketbase.umd.js) foi incluído antes do Easy PocketBase Manager.

Exemplo de configuração personalizada:

// Exemplo de configuração personalizada
const pbManager = new PocketBaseManager({
  baseUrl: 'https://meuservidor.com',
  collection: 'clientes',
  cacheEnabled: true,        // Habilita o cache
  cacheExpirationMinutes: 120, // Expira o cache após 120 minutos
  syncIntervalMinutes: 15,  // Sincronização periódica de 15 em 15 minutos
  persistenceEnabled: true  // Habilita persistência de logs, sessões e análises via IndexedDB
});

Uso e Integração

Após a instalação e configuração, o Easy PocketBase Manager estará pronto para uso. A seguir, descrevemos como interagir com o sistema e integrar as funcionalidades do PocketBase no fluxo da sua aplicação:

Autenticação de Usuários: Utilize os métodos login, signup, logout, logoutAndClear, sendPasswordResetEmail e verifyEmail para gerenciar a autenticação de usuários.
Operações CRUD: Utilize os métodos create, read, update, delete para gerenciar registros nas coleções do PocketBase.
Operações em Lote: Utilize os métodos batchCreate, batchUpdate, batchDelete para realizar operações em múltiplos registros simultaneamente.
Manipulação de Arquivos: Utilize os métodos uploadFile, uploadMultipleFiles, downloadFile, deleteFile, getFileUrl e getMultipleFileUrls para gerenciar arquivos associados a registros.
Gerenciamento de Roles: Utilize os métodos assignRole e getRoles para controlar as permissões de usuários.
Eventos: Escute eventos como 'auth', 'signup', 'passwordResetRequested', 'emailVerified', 'create', 'read', 'update', 'delete', 'list', 'batchCreate', 'batchUpdate', 'batchDelete', 'fileUploaded', 'fileDeleted', 'increment', 'decrement', 'roleAssigned', 'rolesFetched', 'import', 'sync', entre outros, para reagir a ações específicas na aplicação. Você pode utilizar on, once, removeListener e emit para manipular eventos locais.
Exportação e Importação de Dados: Utilize os métodos exportToJSON, importFromJSON, exportToCSV, importFromCSV, exportToXML, importFromXML para exportar e importar dados em formatos JSON, CSV e XML.
Sincronização de Dados: Utilize o método sync para sincronizar dados entre diferentes instâncias do PocketBaseManager. Você também pode iniciar e parar a sincronização periódica com startSync e stopSync.
Cache de Dados: Utilize os métodos clearCache, invalidateRecord para gerenciar o cache de dados.
Leitura com Atualização Automática: Utilize os métodos readWithAutoUpdate e listWithAutoUpdate para ler registros com atualização automática de dados (assinando eventos em tempo real).
Análise de Operações: Utilize os métodos getAnalytics, resetAnalytics, exportAnalytics para obter e gerenciar estatísticas sobre as operações realizadas.
Gerenciamento de Sessões: Utilize os métodos getSessions, endSession, updateSessionActivity, deleteSession, clearSessions, exportSessions para gerenciar sessões de usuários.
Gerenciamento de Logs de Auditoria: Utilize os métodos getAuditLogs, deleteAuditLog, clearAuditLogs, exportAuditLogs para gerenciar logs de auditoria.
Métodos Adicionais: Utilize os métodos cloneRecord, countRecords, searchRecords, increment, decrement, downloadAsJSON, downloadAsCSV e downloadAsXML para funcionalidades avançadas de manipulação de dados.
Configuração da Coleção Padrão: Utilize o método setDefaultCollection para definir a coleção padrão para as operações.

Exemplo de uso básico:

Autenticação de Usuário

// Realiza login de um usuário
pbManager.login('usuario@exemplo.com', 'senha_segura')
  .then((authData) => {
    console.log('Usuário autenticado:', authData);
  })
  .catch((error) => {
    console.error('Erro ao autenticar usuário:', error);
  });

Criação de um Registro

// Cria um novo registro na coleção padrão
pbManager.create({ nome: 'João', idade: 30 })
  .then((registro) => {
    console.log('Registro criado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao criar registro:', error);
  });

Leitura de um Registro

// Lê um registro pelo ID na coleção padrão
pbManager.read('registroId123')
  .then((registro) => {
    console.log('Registro encontrado:', registro);
  })
  .catch((error) => {
    console.error('Erro ao ler registro:', error);
  });

Leitura com Atualização Automática

// Lê um registro e atualiza automaticamente quando há novas informações
pbManager.readWithAutoUpdate('registroId123', 'clientes', (registroAtualizado) => {
  console.log('Registro atualizado automaticamente:', registroAtualizado);
});

Leitura de Lista com Atualização Automática

// Lê uma lista de registros e atualiza automaticamente quando há novas informações
pbManager.listWithAutoUpdate({ page: 1, perPage: 10, filter: 'idade > 25' }, 'clientes', (registrosAtualizados) => {
  console.log('Lista de registros atualizada automaticamente:', registrosAtualizados);
});

Atualização de um Registro

// Atualiza um registro pelo ID na coleção padrão
pbManager.update('registroId123', { idade: 31 })
  .then((registroAtualizado) => {
    console.log('Registro atualizado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao atualizar registro:', error);
  });

Deleção de um Registro

// Deleta um registro pelo ID na coleção padrão
pbManager.delete('registroId123')
  .then((response) => {
    console.log('Registro deletado:', response);
  })
  .catch((error) => {
    console.error('Erro ao deletar registro:', error);
  });

Logout e Limpeza de Dados

// Realiza logout e limpa todos os dados persistidos
pbManager.logoutAndClear()
  .then(() => {
    console.log('Usuário desautenticado e dados limpos com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao desautenticar e limpar dados:', error);
  });

Operações em Lote

// Cria múltiplos registros em lote
const novosRegistros = [
  { nome: 'Mariana', email: 'mariana@exemplo.com', idade: 22 },
  { nome: 'Felipe', email: 'felipe@exemplo.com', idade: 29 }
];

pbManager.batchCreate(novosRegistros)
  .then((registrosCriados) => {
    console.log('Registros criados em lote:', registrosCriados);
  })
  .catch((error) => {
    console.error('Erro ao criar registros em lote:', error);
  });

// Atualiza múltiplos registros em lote
const atualizacoes = {
  'registroId1': { idade: 23 },
  'registroId2': { idade: 30 }
};

pbManager.batchUpdate(atualizacoes)
  .then((registrosAtualizados) => {
    console.log('Registros atualizados em lote:', registrosAtualizados);
  })
  .catch((error) => {
    console.error('Erro ao atualizar registros em lote:', error);
  });

// Deleta múltiplos registros em lote
const idsParaDeletar = ['registroId1', 'registroId2'];

pbManager.batchDelete(idsParaDeletar)
  .then((respostas) => {
    console.log('Registros deletados em lote:', respostas);
  })
  .catch((error) => {
    console.error('Erro ao deletar registros em lote:', error);
  });

Manipulação de Arquivos

// Faz upload de um arquivo para um registro específico
const arquivo = document.querySelector('#inputArquivo').files[0];
const recordId = 'registroId123';
const campoArquivo = 'documento';

pbManager.uploadFile(arquivo, 'clientes', recordId, campoArquivo)
  .then(({ record, fileUrl }) => {
    console.log('Arquivo enviado:', record);
    console.log('URL do arquivo:', fileUrl);
  })
  .catch((error) => {
    console.error('Erro ao enviar arquivo:', error);
  });

// Faz upload de múltiplos arquivos para um registro específico
const arquivos = document.querySelector('#inputArquivos').files;
const recordIdMulti = 'registroId456';
const campoArquivoMulti = 'documentos';

pbManager.uploadMultipleFiles(arquivos, 'clientes', recordIdMulti, campoArquivoMulti)
  .then((resultados) => {
    console.log('Arquivos enviados (resultados):', resultados);
  })
  .catch((error) => {
    console.error('Erro ao enviar arquivos:', error);
  });

// Faz download de um arquivo a partir de uma URL
const fileUrl = 'https://meuservidor.com/files/documento.pdf';

pbManager.downloadFile(fileUrl)
  .then((blob) => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'documento.pdf';
    document.body.appendChild(a);
    a.click();
    a.remove();
  })
  .catch((error) => {
    console.error('Erro ao baixar arquivo:', error);
  });

// Exclui um arquivo de um registro (campo "documento")
pbManager.deleteFile('registroId123', 'documento', 'clientes')
  .then(() => {
    console.log('Arquivo excluído do registro com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao excluir arquivo:', error);
  });

// Obtém a URL de um arquivo específico
pbManager.getFileUrl('registroId123', 'documento', 'clientes')
  .then((urlDoArquivo) => {
    console.log('URL do arquivo:', urlDoArquivo);
  })
  .catch((error) => {
    console.error('Erro ao obter URL do arquivo:', error);
  });

// Obtém as URLs de múltiplos arquivos armazenados em um array de strings
pbManager.getMultipleFileUrls('registroId789', 'documentos', 'clientes')
  .then((urlsDosArquivos) => {
    console.log('URLs dos arquivos:', urlsDosArquivos);
  })
  .catch((error) => {
    console.error('Erro ao obter múltiplas URLs de arquivos:', error);
  });

Gerenciamento de Roles

// Atribui um role a um usuário
const userId = 'usuarioId123';
const roleId = 'roleId456';

pbManager.assignRole(userId, roleId)
  .then((registroAtualizado) => {
    console.log('Role atribuída:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao atribuir role:', error);
  });

// Recupera todos os roles (ou usuários, dependendo da implementação) disponíveis
pbManager.getRoles()
  .then((roles) => {
    console.log('Roles disponíveis:', roles);
  })
  .catch((error) => {
    console.error('Erro ao obter roles:', error);
  });

Exportação e Importação de Dados

// Exporta todos os registros da coleção 'clientes' para JSON
pbManager.exportToJSON('clientes')
  .then((jsonData) => {
    console.log('Dados exportados:', jsonData);
  })
  .catch((error) => {
    console.error('Erro ao exportar dados:', error);
  });

// Importa dados a partir de uma string JSON para a coleção 'clientes'
const dadosImportados = '[{"nome":"Laura","email":"laura@exemplo.com","idade":27}]';

pbManager.importFromJSON(dadosImportados, true, 'clientes')
  .then(() => {
    console.log('Dados importados com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao importar dados:', error);
  });

// Exporta todos os registros da coleção 'clientes' para CSV
pbManager.exportToCSV('clientes')
  .then((csvData) => {
    console.log('Dados exportados para CSV:', csvData);
  })
  .catch((error) => {
    console.error('Erro ao exportar dados para CSV:', error);
  });

// Importa dados a partir de uma string CSV para a coleção 'clientes'
const dadosCSV = 'nome,email,idade\nLaura,laura@exemplo.com,27\nPedro,pedro@exemplo.com,28';

pbManager.importFromCSV(dadosCSV, true, 'clientes')
  .then(() => {
    console.log('Dados importados a partir de CSV com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao importar dados de CSV:', error);
  });

// Exporta todos os registros da coleção 'clientes' para XML
pbManager.exportToXML('clientes')
  .then((xmlData) => {
    console.log('Dados exportados para XML:', xmlData);
  })
  .catch((error) => {
    console.error('Erro ao exportar dados para XML:', error);
  });

// Importa dados a partir de uma string XML para a coleção 'clientes'
const dadosXML = '<?xml version="1.0" encoding="UTF-8"?><records><record><nome>Laura</nome><email>laura@exemplo.com</email><idade>27</idade></record></records>';

pbManager.importFromXML(dadosXML, true, 'clientes')
  .then(() => {
    console.log('Dados importados a partir de XML com sucesso!');
  })
  .catch((error) => {
    console.error('Erro ao importar dados de XML:', error);
  });

Além de exportar os dados para variáveis, você também pode fazer o download imediato dos arquivos gerados pelos métodos de exportação. Veja abaixo exemplos para JSON, CSV e XML:

// Download do arquivo JSON exportado
pbManager.downloadAsJSON('clientes_export.json')
  .then(() => {
    console.log('Download de JSON concluído!');
  })
  .catch((error) => {
    console.error('Erro ao fazer download de JSON:', error);
  });

// Download do arquivo CSV exportado
pbManager.downloadAsCSV('clientes_export.csv')
  .then(() => {
    console.log('Download de CSV concluído!');
  })
  .catch((error) => {
    console.error('Erro ao fazer download de CSV:', error);
  });

// Download do arquivo XML exportado
pbManager.downloadAsXML('clientes_export.xml')
  .then(() => {
    console.log('Download de XML concluído!');
  })
  .catch((error) => {
    console.error('Erro ao fazer download de XML:', error);
  });

Incrementos e Decrementos

// Incrementa o valor de um campo numérico em um registro
pbManager.increment('registroId123', 'quantidade', 5, 'estoque')
  .then((registroAtualizado) => {
    console.log('Valor incrementado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao incrementar valor:', error);
  });

// Decrementa o valor de um campo numérico em um registro
pbManager.decrement('registroId123', 'quantidade', 2, 'estoque')
  .then((registroAtualizado) => {
    console.log('Valor decrementado:', registroAtualizado);
  })
  .catch((error) => {
    console.error('Erro ao decrementar valor:', error);
  });

Eventos Locais (EventEmitter)

// Exemplo de uso do sistema de eventos locais do PocketBaseManager

// Adiciona um listener para o evento 'create'
pbManager.on('create', (novoRegistro) => {
  console.log('Registro criado (evento local):', novoRegistro);
});

// Adiciona um listener de uso único para o evento 'update'
pbManager.once('update', (registroAtualizado) => {
  console.log('Registro atualizado (evento local - once):', registroAtualizado);
});

// Remove um listener (se necessário, passando a mesma função de callback usada em 'on' ou 'once')
// pbManager.removeListener('create', minhaFuncaoCallback);

// Dispara manualmente um evento local
pbManager.emit('create', { id: 'teste', data: { exemplo: true } });

Referência da API

Métodos Principais

constructor(options): Cria uma nova instância do PocketBaseManager.
Parâmetros:
- options (Object): Configurações iniciais, como baseUrl, collection, cacheEnabled, cacheExpirationMinutes, syncIntervalMinutes, persistenceEnabled.
isAuthenticated(): Verifica se o usuário está autenticado.
Retorna: true se autenticado, false caso contrário.
login(email, password): Realiza o login de um usuário.
Parâmetros:
- email (String): Email do usuário.
- password (String): Senha do usuário.
Retorna: Promise que resolve com os dados de autenticação.
getUserId(): Retorna o ID do usuário atualmente autenticado (se houver).
Retorna: String (ID do usuário) ou undefined se não estiver autenticado.
signup(email, password, data): Registra um novo usuário.
Parâmetros:
- email (String): Email do usuário.
- password (String): Senha do usuário.
- data (Object, opcional): Dados adicionais do usuário.
Retorna: Promise que resolve com o registro criado.
sendPasswordResetEmail(email): Envia um email para redefinição de senha.
Parâmetros:
- email (String): Email do usuário.
Retorna: Promise que resolve quando o email for enviado.
verifyEmail(token): Verifica o email do usuário com um token.
Parâmetros:
- token (String): Token de verificação.
Retorna: Promise que resolve com os dados de verificação.
logout(): Realiza o logout do usuário.
Retorna: Promise que resolve quando o logout for concluído.
logoutAndClear(): Realiza o logout do usuário e limpa todos os dados persistidos (logs de auditoria, sessões, análises e cache).
Retorna: Promise que resolve quando o logout e a limpeza forem concluídos.
create(data, collection): Cria um novo registro em uma coleção.
Parâmetros:
- data (Object): Dados do registro.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com o registro criado.
read(id, collection): Lê um registro pelo ID.
Parâmetros:
- id (String): ID do registro.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com o registro.
readWithAutoUpdate(id, collection, updateCallback): Lê um registro pelo ID e atualiza automaticamente quando há novas informações (através de eventos em tempo real).
Parâmetros:
- id (String): ID do registro.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
- updateCallback (Function): Função a ser chamada com o registro atualizado.
Retorna: Promise que resolve com os dados do registro inicial.
list(params, collection): Lista registros com parâmetros de consulta.
Parâmetros:
- params (Object): Parâmetros de listagem, como page, perPage, filter.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com a lista de registros.
listWithAutoUpdate(params, collection, updateCallback): Lista registros com parâmetros de consulta e atualiza automaticamente quando há novas informações (assinatura em tempo real).
Parâmetros:
- params (Object): Parâmetros de listagem, como page, perPage, filter.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
- updateCallback (Function): Função a ser chamada com a lista atualizada.
Retorna: Promise que resolve com a lista inicial de registros.
update(id, data, collection): Atualiza um registro existente.
Parâmetros:
- id (String): ID do registro.
- data (Object): Dados a serem atualizados.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com o registro atualizado.
delete(id, collection): Deleta um registro pelo ID.
Parâmetros:
- id (String): ID do registro.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com a resposta da deleção.
batchCreate(dataArray, collection): Cria múltiplos registros em lote.
Parâmetros:
- dataArray (Array): Array de objetos de dados.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com os registros criados.
batchUpdate(idDataMap, collection): Atualiza múltiplos registros em lote.
Parâmetros:
- idDataMap (Object): Mapa de IDs para dados de atualização.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com os registros atualizados.
batchDelete(ids, collection): Deleta múltiplos registros em lote.
Parâmetros:
- ids (Array): Array de IDs dos registros.
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
Retorna: Promise que resolve com as respostas das deleções.
subscribe(event, collection, callback): Assina um evento específico em uma coleção no PocketBase (tempo real).
Parâmetros:
- event (String): Nome do evento (ex.: 'create', 'update', 'delete', '*').
- collection (String, opcional): Nome da coleção. Se não especificado, usa a coleção padrão.
- callback (Function): Função a ser chamada quando o evento ocorrer.
Retorna: Promise que resolve com a função de desinscrição.
unsubscribe(unsubscribeFn): Desinscreve de um evento de tempo real.
Parâmetros:
- unsubscribeFn (Function): Função de desinscrição retornada pelo método subscribe.
Retorna: Promise que resolve quando a desinscrição for concluída.
uploadFile(file, collection, recordId, field): Faz upload de um arquivo para uma coleção ou registro específico.
Parâmetros:
- file (File): Arquivo a ser enviado.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
- recordId (String, opcional): ID do registro para associar o arquivo (cria um novo registro se não fornecido).
- field (String, opcional): Nome do campo onde o arquivo será armazenado (padrão: 'file').
Retorna: Promise que resolve com um objeto contendo o registro atualizado e a URL do arquivo (fileUrl).
uploadMultipleFiles(files, collection, recordId, field): Faz upload de múltiplos arquivos para uma coleção ou registro específico.
Parâmetros:
- files (FileList ou Array): Arquivos a serem enviados.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
- recordId (String, opcional): ID do registro para associar os arquivos (cria novos registros se não fornecido).
- field (String, opcional): Nome do campo onde os arquivos serão armazenados (padrão: 'file').
Retorna: Promise que resolve com um array de resultados, cada um contendo o registro atualizado ou um objeto de erro.
downloadFile(fileUrl): Faz download de um arquivo a partir de uma URL (fetch + blob).
Parâmetros:
- fileUrl (String): URL do arquivo.
Retorna: Promise que resolve com o Blob do arquivo.
deleteFile(recordId, fieldName, collection): Remove um arquivo específico de um registro, definindo o campo para null.
Parâmetros:
- recordId (String): ID do registro.
- fieldName (String): Nome do campo que armazena o arquivo.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve quando o arquivo for removido do registro.
getFileUrl(recordId, fieldName, collection): Retorna a URL de um arquivo específico armazenado em um registro.
Parâmetros:
- recordId (String): ID do registro.
- fieldName (String): Nome do campo que armazena o arquivo.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com a URL do arquivo.
getMultipleFileUrls(recordId, fieldName, collection): Retorna um array de URLs para arquivos armazenados em um campo do tipo array.
Parâmetros:
- recordId (String): ID do registro.
- fieldName (String): Nome do campo que armazena um array de nomes de arquivos.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com um array de URLs.
assignRole(userId, roleId, collection): Atribui um role a um usuário.
Parâmetros:
- userId (String): ID do usuário.
- roleId (String): ID ou identificador do role.
- collection (String, opcional): Nome da coleção de usuários (padrão: 'users').
Retorna: Promise que resolve com o registro atualizado.
getRoles(collection): Recupera todos os roles (ou registros de usuários) de uma coleção.
Parâmetros:
- collection (String, opcional): Nome da coleção (padrão: 'users').
Retorna: Promise que resolve com a lista de roles (ou registros).
exportToJSON(collection): Exporta todos os registros de uma coleção para uma string JSON.
Parâmetros:
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com a string JSON.
importFromJSON(jsonData, overwrite, collection): Importa registros a partir de uma string JSON.
Parâmetros:
- jsonData (String): String JSON contendo os dados a serem importados.
- overwrite (Boolean, opcional): Se true, sobrescreve registros existentes. Padrão: false.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve quando a importação for concluída.
downloadAsJSON(filename): Exporta todos os registros da coleção padrão (ou especificada) e inicia o download do arquivo JSON resultante.
Parâmetros:
- filename (String, opcional): Nome do arquivo a ser baixado (por padrão inclui timestamp).
Retorna: Promise que se resolve quando o download é acionado (ou rejeita em caso de erro).
exportToCSV(collection): Exporta todos os registros de uma coleção para uma string CSV.
Parâmetros:
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com a string CSV.
importFromCSV(csvData, overwrite, collection): Importa registros a partir de uma string CSV.
Parâmetros:
- csvData (String): String CSV contendo os dados a serem importados.
- overwrite (Boolean, opcional): Se true, sobrescreve registros existentes. Padrão: false.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve quando a importação for concluída.
downloadAsCSV(filename): Exporta todos os registros da coleção padrão (ou especificada) para CSV e inicia o download do arquivo.
Parâmetros:
- filename (String, opcional): Nome do arquivo a ser baixado (por padrão inclui timestamp).
Retorna: Promise que se resolve quando o download é acionado (ou rejeita em caso de erro).
exportToXML(collection): Exporta todos os registros de uma coleção para uma string XML.
Parâmetros:
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com a string XML.
importFromXML(xmlData, overwrite, collection): Importa registros a partir de uma string XML.
Parâmetros:
- xmlData (String): String XML contendo os dados a serem importados.
- overwrite (Boolean, opcional): Se true, sobrescreve registros existentes. Padrão: false.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve quando a importação for concluída.
downloadAsXML(filename): Exporta todos os registros da coleção padrão (ou especificada) para XML e inicia o download do arquivo.
Parâmetros:
- filename (String, opcional): Nome do arquivo a ser baixado (por padrão inclui timestamp).
Retorna: Promise que se resolve quando o download é acionado (ou rejeita em caso de erro).
cloneRecord(id, collection): Clona um registro existente.
Parâmetros:
- id (String): ID do registro a ser clonado.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com o novo registro clonado.
countRecords(filter, collection): Conta o número de registros que correspondem a um filtro específico.
Parâmetros:
- filter (String, opcional): Filtro para contagem.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com o total de registros que correspondem ao filtro.
searchRecords(filter, collection): Busca registros que correspondem a um filtro específico.
Parâmetros:
- filter (String): Filtro para busca.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com os registros encontrados.
sync(other): Sincroniza dados com outra instância do PocketBaseManager.
Parâmetros:
- other (PocketBaseManager): Outra instância do PocketBaseManager para sincronizar.
Retorna: Promise que resolve quando a sincronização for concluída.
clearCache(): Limpa todo o cache de dados.
Retorna: Promise que resolve quando o cache for limpo.
invalidateRecord(id): Invalida um registro específico no cache.
Parâmetros:
- id (String): ID do registro a ser invalidado.
Retorna: Promise que resolve quando o registro for invalidado.
increment(id, field, amount, collection): Incrementa o valor numérico de um campo em um registro.
Parâmetros:
- id (String): ID do registro.
- field (String): Nome do campo a ser incrementado.
- amount (Number): Valor a ser adicionado.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com o registro atualizado.
decrement(id, field, amount, collection): Decrementa o valor numérico de um campo em um registro.
Parâmetros:
- id (String): ID do registro.
- field (String): Nome do campo a ser decrementado.
- amount (Number): Valor a ser subtraído.
- collection (String, opcional): Nome da coleção (padrão: coleção definida no construtor).
Retorna: Promise que resolve com o registro atualizado.
startSync(): Inicia o processo de sincronização periódica de dados (baseado em syncIntervalMinutes).
Retorna: void.
stopSync(): Interrompe o processo de sincronização periódica de dados.
Retorna: void.
getAnalytics(): Obtém os dados de análise das operações realizadas.
Retorna: Objeto contendo contagens de operações e uso de bytes.
resetAnalytics(): Reseta os dados de análise das operações realizadas.
Retorna: void.
exportAnalytics(): Exporta os dados de análise das operações para uma string JSON.
Retorna: String JSON contendo os dados de análise.
setDefaultCollection(collection): Define a coleção padrão para as operações.
Parâmetros:
- collection (String): Nome da coleção.
Retorna: void.
getAuditLogs(options): Obtém os logs de auditoria com opções de filtro, ordenação e busca.
Parâmetros:
- options (Object, opcional): Objeto contendo filter, sortBy, searchTerm.
Retorna: Array de logs de auditoria.
deleteAuditLog(index): Deleta um log de auditoria específico pelo índice.
Parâmetros:
- index (Number): Índice do log a ser deletado.
Retorna: void.
clearAuditLogs(): Limpa todos os logs de auditoria.
Retorna: void.
exportAuditLogs(): Exporta todos os logs de auditoria para uma string JSON.
Retorna: String JSON contendo os logs de auditoria.
getSessions(): Obtém todas as sessões atuais.
Retorna: Array de sessões.
endSession(sessionId): Encerra uma sessão específica.
Parâmetros:
- sessionId (String): ID da sessão a ser encerrada.
Retorna: void.
updateSessionActivity(sessionId, activity): Atualiza a atividade de uma sessão específica.
Parâmetros:
- sessionId (String): ID da sessão.
- activity (String): Descrição da atividade.
Retorna: void.
deleteSession(sessionId): Deleta uma sessão específica (sem disparar log de auditoria).
Parâmetros:
- sessionId (String): ID da sessão a ser deletada.
Retorna: void.
clearSessions(): Limpa todas as sessões.
Retorna: void.
exportSessions(): Exporta todas as sessões para uma string JSON.
Retorna: String JSON contendo as sessões.
on(event, callback): Adiciona um listener para um evento local específico (emitido internamente pelo gerenciador).
Parâmetros:
- event (String): Nome do evento.
- callback (Function): Função a ser executada quando o evento ocorrer.
once(event, callback): Adiciona um listener para um evento local que dispara apenas uma vez.
Parâmetros:
- event (String): Nome do evento.
- callback (Function): Função a ser executada quando o evento ocorrer pela primeira vez.
removeListener(event, callback): Remove um listener previamente adicionado para um evento local.
Parâmetros:
- event (String): Nome do evento.
- callback (Function): A mesma função que foi usada em on ou once.
emit(event, ...args): Emite manualmente um evento local, disparando todos os callbacks registrados para ele.
Parâmetros:
- event (String): Nome do evento.
- ...args (qualquer): Argumentos adicionais passados aos callbacks.

Eventos Disponíveis

auth: Disparado quando o status de autenticação muda.
signup: Disparado quando um novo usuário se registra.
passwordResetRequested: Disparado quando um pedido de redefinição de senha é feito.
emailVerified: Disparado quando o email de um usuário é verificado.
create: Disparado quando um novo registro é criado.
read: Disparado quando um registro é lido.
update: Disparado quando um registro é atualizado.
delete: Disparado quando um registro é deletado.
list: Disparado quando uma lista de registros é recuperada.
batchCreate: Disparado quando múltiplos registros são criados em lote.
batchUpdate: Disparado quando múltiplos registros são atualizados em lote.
batchDelete: Disparado quando múltiplos registros são deletados em lote.
fileUploaded: Disparado quando um arquivo é enviado com sucesso.
fileDeleted: Disparado quando um arquivo é removido de um registro.
increment: Disparado quando um valor numérico de um registro é incrementado.
decrement: Disparado quando um valor numérico de um registro é decrementado.
roleAssigned: Disparado quando um role é atribuído a um usuário.
rolesFetched: Disparado quando os roles são recuperados.
import: Disparado quando dados são importados via JSON, CSV ou XML.
sync: Disparado quando a sincronização de dados é concluída.

Configurações de Inicialização

baseUrl (String): URL base do servidor PocketBase. Padrão: 'http://127.0.0.1:8090'.
collection (String): Nome da coleção padrão a ser utilizada nas operações CRUD. Padrão: null.
cacheEnabled (Boolean): Habilita ou desabilita o cache de dados utilizando IndexedDB. Padrão: true.
cacheExpirationMinutes (Number): Define o tempo de expiração do cache em minutos. Padrão: 60.
syncIntervalMinutes (Number): Define o intervalo de sincronização de dados em minutos. Padrão: 10.
persistenceEnabled (Boolean): Habilita ou desabilita a persistência de dados (logs de auditoria, sessões e análises) utilizando IndexedDB. Padrão: true.

Resolução de Problemas

Enfrentando problemas com o Easy PocketBase Manager? Aqui estão algumas soluções para problemas comuns:

PocketBaseManager Não Inicializa: Verifique se o script do PocketBase está sendo carregado corretamente antes do script do PocketBase Manager.
Erro de Conexão com o PocketBase: Assegure-se de que a baseUrl está correta e que o servidor PocketBase está em execução e acessível.
Falha na Autenticação: Verifique se as credenciais fornecidas estão corretas e se o usuário existe na coleção de usuários.
Operações CRUD Não Funcionam: Certifique-se de que a coleção especificada existe no PocketBase e que o usuário possui as permissões necessárias para realizar as operações.
Operações em Lote Não Funcionam: Verifique se os dados fornecidos estão no formato correto e se as coleções suportam operações em lote.
Falha na Manipulação de Arquivos: Verifique se o campo especificado para o upload de arquivo existe na coleção e se o arquivo está no formato correto.
Eventos Não São Disparados: Assegure-se de que os listeners de eventos estão corretamente configurados utilizando os métodos on, once e que os eventos estão sendo emitidos conforme esperado.
Falha na Importação/Exportação de Dados: Confirme se o formato do JSON, CSV ou XML está correto e se os dados correspondem à estrutura esperada pela coleção.
Sincronização de Dados Não Funciona: Verifique se ambas as instâncias do PocketBaseManager estão configuradas corretamente e se a conexão com o PocketBase está estável.
Problemas de Permissões: Assegure-se de que as permissões das coleções no PocketBase estão configuradas para permitir as operações desejadas.
Erro ao Atribuir Roles: Verifique se os IDs de usuário e role fornecidos estão corretos e se a coleção de usuários possui um campo para armazenar roles.
Problemas com o Cache: Utilize os métodos clearCache, invalidateRecord para gerenciar e resolver problemas relacionados ao cache.
Falha na Leitura com Atualização Automática: Verifique se os callbacks estão corretamente implementados e se os eventos de atualização estão sendo assinados via subscribe (internamente chamado em readWithAutoUpdate ou listWithAutoUpdate).
Falha ao Gerenciar Sessões: Certifique-se de que os métodos de gerenciamento de sessões estão sendo utilizados corretamente e que as sessões estão sendo armazenadas e atualizadas conforme esperado.
Falha ao Gerenciar Logs de Auditoria: Verifique se os métodos de auditoria estão sendo chamados corretamente e se os logs estão sendo armazenados e filtrados conforme esperado.

Exemplos de Código

Abaixo, alguns exemplos de como integrar e utilizar o Easy PocketBase Manager:

Exemplo Básico de Integração

<!-- Inclusão do Script do PocketBase -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/pocketbase/0.25.0/pocketbase.umd.js"></script>

<!-- Inclusão do Script do PocketBase Manager -->
<script src="https://cdn.alphasystem.dev/plugins/easy-pocketbase-manager/latest/script-min.js"></script>

<!-- Script de Configuração e Inicialização -->
<script>
  const pbManager = new PocketBaseManager({
    baseUrl: 'https://meuservidor.com',
    collection: 'clientes',
    cacheEnabled: true,
    cacheExpirationMinutes: 120,
    syncIntervalMinutes: 15,
    persistenceEnabled: true
  });
</script>