zenidb

v1.0.5

Published

13 days ago

Uma SDK de banco de dados simples, rápida e com suporte a criptografia AES-256

0High
0Medium
0Low

caiox

database json db storage key-value encrypted encryption aes-256 sdk zenidb typescript

🔐 ZenIDB

Uma SDK de banco de dados simples, rápida e com suporte a criptografia AES-256 pra Node.js. Perfeita pra quem quer algo leve e fácil de usar!

✨ Características

🔒 Criptografia AES-256 opcional (bem segura!)
⚡ Síncrono - Sem callbacks ou promises, direto ao ponto
🎯 Nested keys - Suporta "user.profile.name" sem problemas
👀 Watchers - Observa mudanças em tempo real
💾 Backup automático - Nunca perca seus dados
🔄 Auto-set opcional - Cria chaves automaticamente se quiser
📦 Zero dependências - Leve e rápido
📘 TypeScript - Totalmente tipado, autocomplete funciona perfeitamente

📦 Instalação

npm install zenidb

Bem simples né? Só isso mesmo!

🚀 Uso Básico

JavaScript

const { Database } = require('zenidb');

// Criar instância (bem fácil)
const db = new Database('./database.json');

// Set - salvar dados
db.set('usuario', 'João');
db.set('user.profile.name', 'João Silva'); // Nested keys funcionam perfeitamente

// Get - pegar dados
const usuario = db.get('usuario');
const nome = db.get('user.profile.name');

// Has - verificar se existe
if (db.has('usuario')) {
  console.log('Usuário existe!');
}

// Delete - deletar
db.delete('usuario');

TypeScript

import { Database } from 'zenidb';

// Criar instância
const db = new Database('./database.json');

// Set com tipos (TypeScript é massa!)
db.set<string>('usuario', 'João');
db.set<string>('user.profile.name', 'João Silva');

// Get com tipos
const usuario: string = db.get<string>('usuario')!;
const nome: string = db.get<string>('user.profile.name')!;

// Has
if (db.has('usuario')) {
  console.log('Usuário existe!');
}

// Delete
db.delete('usuario');

🔐 Criptografia

Quer proteger seus dados? É só passar uma senha na criação:

const db = new Database('./database.json', {
  encrypt: 'minha-senha-secreta'
});

// Agora tudo fica criptografado automaticamente
db.set('senha', '123456');

Os dados ficam seguros no arquivo, mas você acessa normalmente no código. Bem prático!

📊 Arrays

Trabalhar com arrays é bem simples:

// Push - adicionar itens
db.push('lista', 'item1');
db.push('lista', 'item2');

// Pull - remover itens (usa função de filtro)
db.pull('lista', item => item === 'item1');

// Find - encontrar um item específico
const item = db.find('lista', item => item.startsWith('item'));

🔢 Operações Matemáticas

Pra trabalhar com números, tem funções bem úteis:

// Set valor inicial
db.set('pontos', 0);

// Add - somar valores
db.add('pontos', 10); // 10
db.add('pontos', 5);  // 15

// Incrementar (padrão é +1)
db.inc('pontos');     // 16
db.inc('pontos', 5);  // 21

// Decrementar (padrão é -1)
db.dec('pontos');     // 20
db.dec('pontos', 5);  // 15

🔄 Boolean

Alternar valores booleanos é super fácil:

db.set('ativo', true);
db.toggle('ativo'); // false
db.toggle('ativo'); // true

👀 Watchers

Quer saber quando algo muda? Use watchers:

db.watch('usuario', (oldValue, newValue) => {
  console.log(`Mudou de ${oldValue} para ${newValue}`);
});

db.set('usuario', 'Maria'); // Dispara o watcher automaticamente

Bem útil pra fazer coisas quando dados mudam!

💾 Backup

Fazer backup é moleza:

// Backup com nome automático (usa timestamp)
const fileName = db.backup(); // backup-1234567890.json

// Ou com nome customizado
db.backup('meu-backup.json');

Os backups ficam na pasta backups/ automaticamente.

🔍 Busca Avançada

Buscar chaves é bem fácil:

// Buscar chaves que começam com prefixo
const usuarios = db.startsWith('user.'); // ['user.name', 'user.email', 'user.age']

// Buscar chaves que terminam com sufixo
const nomes = db.endsWith('.name'); // ['user.name', 'admin.name']

// Buscar chaves que contêm texto
const perfis = db.includes('profile'); // ['user.profile', 'admin.profile']

// Busca profunda em objetos aninhados
const resultados = db.deepFind((key, value) => value === 'João');
// [{ key: 'user.name', value: 'João' }, { key: 'admin.name', value: 'João' }]

// Encontrar todas as chaves com um valor específico
const chaves = db.findByValue('João'); // ['user.name', 'admin.name']

📊 Arrays Avançados

Tem várias funções úteis pra trabalhar com arrays:

// Map - transformar array
db.map('lista', item => item.toUpperCase());

// Reduce - reduzir a um valor
const soma = db.reduce('numeros', (acc, val) => acc + val, 0);

// Some - verificar se algum satisfaz
if (db.some('lista', item => item > 10)) {
  console.log('Tem item maior que 10!');
}

// Every - verificar se todos satisfazem
if (db.every('lista', item => item > 0)) {
  console.log('Todos são positivos!');
}

// Includes - verificar se contém
if (db.includesArray('lista', 'item1')) {
  console.log('Tem item1!');
}

// Unique - remover duplicatas
db.unique('lista');

// Sort - ordenar
db.sort('lista', (a, b) => a.localeCompare(b));

// Take - pegar primeiros N
const primeiros = db.take('lista', 3);

// Skip - pular primeiros N
const restantes = db.skip('lista', 2);

// Count - contar itens
const total = db.count('lista');

// CountBy - contar por condição
const positivos = db.countBy('numeros', n => n > 0);

🔤 Strings

Transformações de string são simples:

db.set('nome', 'joão silva');
db.uppercase('nome'); // 'JOÃO SILVA'
db.lowercase('nome'); // 'joão silva'
db.capitalize('nome'); // 'João silva'

🔀 Merge & Update

Atualizar objetos parcialmente:

// Merge - mesclar objeto
db.set('user', { name: 'João', age: 25 });
db.merge('user', { email: '[email protected]' });
// Resultado: { name: 'João', age: 25, email: '[email protected]' }

// Update - atualizar com função
db.update('pontos', pontos => pontos + 10);

⚖️ Comparação

Comparar valores é fácil:

// Comparar duas chaves
if (db.equals('user1', 'user2')) {
  console.log('São iguais!');
}

// Comparar com valor específico
if (db.isEqual('idade', 25)) {
  console.log('Tem 25 anos!');
}

// Maior/Menor que
if (db.isGreaterThan('pontos', 100)) {
  console.log('Tem mais de 100 pontos!');
}

📁 Path Manipulation

Mover, copiar e renomear chaves:

// Move - mover chave
db.move('user.old', 'user.new');

// Copy - copiar chave
db.copy('user.profile', 'user.backup');

// Rename - renomear
db.rename('oldKey', 'newKey');

⏰ TTL (Time To Live)

Dados que expiram automaticamente:

// Definir com expiração (3600 segundos = 1 hora)
db.setWithTTL('token', 'abc123', 3600);

// Verificar se expirou
if (db.isExpired('token')) {
  console.log('Token expirado!');
}

// Pegar valor (retorna undefined se expirou)
const token = db.getWithTTL('token');

// Limpar todos os expirados
const removidos = db.clearExpired();

📦 Batch Operations

Executar várias operações de uma vez:

// Batch com array de operações
db.batch([
  { type: 'set', key: 'user1', value: 'João' },
  { type: 'set', key: 'user2', value: 'Maria' },
  { type: 'inc', key: 'contador', value: 1 },
  { type: 'delete', key: 'user3' }
]);

// Batch com callback (mais simples)
db.batchCallback(() => {
  db.set('a', 1);
  db.set('b', 2);
  db.set('c', 3);
});

📈 Estatísticas

Ver estatísticas do banco:

const stats = db.stats();
// { size: 10, keys: 10, encrypted: true }

🧬 Clone

Clonar valores e bancos:

// Clonar um valor
const clone = db.clone('user');

// Clonar banco inteiro para novo arquivo
const novoBanco = db.cloneTo('./novo-banco.json');

🔧 Opções

Na hora de criar o banco, você pode passar algumas opções:

const db = new Database('./database.json', {
  encrypt: 'senha-secreta',  // Criptografar os dados
  autoSet: true              // Criar chaves automaticamente no get() se não existirem
});

📚 API Completa

Aqui tem todas as funções disponíveis:

Métodos Básicos

get(key, defaultValue) - Pega um valor (pode passar valor padrão)
set(key, value) - Salva um valor
has(key) - Verifica se a chave existe
delete(key) - Deleta uma chave
reset(key) - Reseta pra null
all() - Pega todos os dados
clear() - Limpa tudo
size() - Retorna quantas chaves tem
isEmpty() - Verifica se tá vazio
keys() - Retorna array com todas as chaves
values() - Retorna array com todos os valores

Busca Avançada

startsWith(prefix) - Busca chaves que começam com prefixo
endsWith(suffix) - Busca chaves que terminam com sufixo
includes(text) - Busca chaves que contêm texto
deepFind(filterFn) - Busca profunda em objetos aninhados
findByValue(value) - Encontra todas as chaves com um valor específico

Arrays

push(key, value) - Adiciona item no array
pull(key, filterFn) - Remove itens do array (usa função)
find(key, filterFn) - Encontra um item no array
map(key, mapFn) - Transforma cada item do array
reduce(key, reduceFn, initialValue) - Reduz array a um valor
some(key, predicate) - Verifica se algum item satisfaz condição
every(key, predicate) - Verifica se todos satisfazem condição
includesArray(key, value) - Verifica se array contém valor
unique(key) - Remove duplicatas
reverse(key) - Reverte ordem do array
sort(key, compareFn) - Ordena array
take(key, count) - Pega primeiros N itens
skip(key, count) - Pula primeiros N itens
count(key) - Conta itens no array
countBy(key, predicate) - Conta itens que satisfazem condição

Números

add(key, value) - Soma valores
inc(key, value = 1) - Incrementa (padrão +1)
dec(key, value = 1) - Decrementa (padrão -1)

Boolean

toggle(key, defaultValue) - Alterna o valor booleano

Strings

uppercase(key) - Converte para maiúsculas
lowercase(key) - Converte para minúsculas
capitalize(key) - Primeira letra maiúscula

Merge & Update

merge(key, partial) - Mescla objeto parcialmente
update(key, updateFn) - Atualiza usando função

Comparação

equals(key1, key2) - Compara valores de duas chaves
isEqual(key, value) - Compara com valor específico
isGreaterThan(key, value) - Verifica se é maior que
isLessThan(key, value) - Verifica se é menor que

Path Manipulation

move(fromKey, toKey) - Move chave para outro caminho
copy(fromKey, toKey) - Copia chave para outro caminho
rename(oldKey, newKey) - Renomeia uma chave

TTL (Time To Live)

setWithTTL(key, value, ttlSeconds) - Define valor com expiração
isExpired(key) - Verifica se expirou
getWithTTL(key, defaultValue) - Pega valor (retorna undefined se expirou)
clearExpired() - Remove todas as chaves expiradas

Batch Operations

batch(operations) - Executa múltiplas operações de uma vez
batchCallback(callback) - Executa operações usando callback

Contagem Avançada

countKeys(prefix) - Conta chaves que começam com prefixo

Objetos

objectKeys(key) - Retorna chaves de um objeto
objectValues(key) - Retorna valores de um objeto
hasKey(key, propertyKey) - Verifica se objeto tem propriedade

Estatísticas

stats() - Retorna estatísticas do banco

Clone

clone(key) - Clona um valor (deep copy)
cloneTo(newFilePath) - Clona banco inteiro para novo arquivo

Utilitários

ensure(key, value) - Garante que a chave existe (cria se não tiver)
watch(key, callback) - Observa mudanças numa chave
backup(name) - Cria backup
export() - Exporta todos os dados
import(data) - Importa dados
forEach(callback) - Itera sobre todas as entradas
filter(filterFn) - Filtra entradas

📄 Licença

Esse projeto ta licenciado sob a Licença MIT.

🤝 Contribuindo

Contribuições são super bem-vindas! Se tiver alguma ideia ou encontrar algum bug, pode abrir uma issue ou fazer um pull request. Toda ajuda é bem vinda! 😊