push()
push(key, …values)
Section titled “push(key, …values)”Adiciona um ou mais elementos ao final de um array.
Sintaxe
Section titled “Sintaxe”const newLength = await db.push(key, ...values)Parâmetros
Section titled “Parâmetros”key(string): A chave do array...values(any[]): Valores a serem adicionados
Retorno
Section titled “Retorno”Promise<number>: O novo comprimento do array
Exemplos
Section titled “Exemplos”Exemplo Básico
Section titled “Exemplo Básico”const { HelperDB } = require('helper.db');const db = new HelperDB();
// Criar array inicialawait db.set('lista', [1, 2, 3]);
// Adicionar um elementoconst novoTamanho = await db.push('lista', 4);console.log(novoTamanho); // 4
const lista = await db.get('lista');console.log(lista); // [1, 2, 3, 4]Múltiplos Elementos
Section titled “Múltiplos Elementos”// Adicionar múltiplos elementos de uma vezawait db.set('frutas', ['maçã', 'banana']);
const tamanho = await db.push('frutas', 'laranja', 'uva', 'pêra');console.log(tamanho); // 5
const frutas = await db.get('frutas');console.log(frutas); // ['maçã', 'banana', 'laranja', 'uva', 'pêra']Arrays Aninhados
Section titled “Arrays Aninhados”await db.set('usuario', { nome: 'João', hobbies: ['leitura', 'música']});
// Adicionar hobby usando notação de pontoawait db.push('usuario.hobbies', 'programação', 'culinária');
const usuario = await db.get('usuario');console.log(usuario.hobbies); // ['leitura', 'música', 'programação', 'culinária']Diferentes Tipos de Dados
Section titled “Diferentes Tipos de Dados”await db.set('misto', []);
// Adicionar diferentes tiposawait db.push('misto', 'string', 42, true, { nome: 'objeto' }, [1, 2, 3], null);
const misto = await db.get('misto');console.log(misto);// ['string', 42, true, { nome: 'objeto' }, [1, 2, 3], null]Comportamentos Especiais
Section titled “Comportamentos Especiais”Array Inexistente
Section titled “Array Inexistente”// Se a chave não existir, cria um novo arrayconst tamanho = await db.push('novo_array', 'primeiro');console.log(tamanho); // 1
const array = await db.get('novo_array');console.log(array); // ['primeiro']Valor Não-Array
Section titled “Valor Não-Array”// Se o valor não for array, converte para arrayawait db.set('nao_array', 'string');
await db.push('nao_array', 'novo_item');const resultado = await db.get('nao_array');console.log(resultado); // ['string', 'novo_item']Arrays de Objetos
Section titled “Arrays de Objetos”await db.set('usuarios', []);
await db.push('usuarios', { id: 1, nome: 'João' }, { id: 2, nome: 'Maria' }, { id: 3, nome: 'Pedro' });
const usuarios = await db.get('usuarios');console.log(usuarios);// [// { id: 1, nome: 'João' },// { id: 2, nome: 'Maria' },// { id: 3, nome: 'Pedro' }// ]Casos de Uso Práticos
Section titled “Casos de Uso Práticos”Sistema de Log
Section titled “Sistema de Log”async function adicionarLog(tipo, mensagem) { const entrada = { timestamp: new Date().toISOString(), tipo, mensagem };
return await db.push('logs', entrada);}
await adicionarLog('info', 'Usuário logado');await adicionarLog('error', 'Falha na conexão');Lista de Tarefas
Section titled “Lista de Tarefas”async function adicionarTarefa(titulo, prioridade = 'normal') { const tarefa = { id: Date.now(), titulo, prioridade, concluida: false, criadaEm: new Date() };
return await db.push('tarefas', tarefa);}
await adicionarTarefa('Estudar JavaScript', 'alta');await adicionarTarefa('Fazer compras', 'baixa');Histórico de Transações
Section titled “Histórico de Transações”async function registrarTransacao(tipo, valor, descricao) { const transacao = { id: crypto.randomUUID(), tipo, // 'entrada' ou 'saida' valor, descricao, data: new Date(), saldo: await calcularSaldoAtual() };
await db.push('transacoes', transacao); return transacao;}
await registrarTransacao('entrada', 1500, 'Salário');await registrarTransacao('saida', 50, 'Almoço');Performance
Section titled “Performance”// ✅ Eficiente - adicionar múltiplos de uma vezawait db.push('lista', item1, item2, item3);
// ❌ Menos eficiente - múltiplas chamadasawait db.push('lista', item1);await db.push('lista', item2);await db.push('lista', item3);
// ✅ Para muitos items, use setManyconst items = Array.from({length: 1000}, (_, i) => `item${i}`);await db.push('lista', ...items);Limitações
Section titled “Limitações”- ⚠️ Não funciona com chaves que não sejam arrays após conversão
- ⚠️ Performance pode degradar com arrays muito grandes (>10k items)
- ⚠️ Operação atômica - falha completa se algum valor for inválido
Eventos Emitidos
Section titled “Eventos Emitidos”db.on('beforePush', (data) => { console.log('Adicionando ao array:', data.key, data.values);});
db.on('push', (data) => { console.log('Array atualizado:', data.key, 'Novo tamanho:', data.newLength);});