library sync-localdb

Para que serve?

sync-localdb é uma biblioteca para desenvolvimento rápido de um software que deseja guardar seus dados sem precisar de conexão e se preocupar com infra-estrutura. Ele também pode servir bem para o caso de aplicações em que deseja utilizar apenas localmente.

Como começar a usar?

npm i sync-localdb

// commonjs
const Localdb = require("sync-localdb");
// es6
import Localdb from "sync-localdb";
// instanciando a classe do banco de dados
const localdb = new Localdb();

Versões:

• v1.0 - Modificado dia 14 de março de 2024
• v2.0 - Modificado dia 28 de março de 2024

Primeiros passos:

1. Criar uma table client

const userTable = localdb.createTable({
    tableName: "users",
    fields: [
        {
            fieldName: "userID",
            fieldType: "string",
            uniqueIndex: true,
            valueDefault: Localdb.value_default.AUTO_INCREMENT
        },
        {
            fieldName: "name",
            fieldType: "string"
        },
        {
            fieldName: "age",
            fieldType: "integer"
        }
    ]
})

deve definir no paramêtro do createTable, com 'fields' ou seja os campos, com um array de objetos contendo no mínimo o nome do campo (fieldName) e o tipo do campo (fieldType), além disso você tbm pode adicionar a propriedade 'optional', 'valueDefault' e 'uniqueIndex'. Abaixo terá mais detalhado sobre oq faz cada propriedade dessas:

• fieldName: deve ser uma string contendo o nome daquele campo, basicamente o nome da coluna da tabela.

• fieldType deve ser uma string ou um array de string, contendo o tipo ou os tipos que aquele campo permite. todos os tipos disponíveis: "any", "string", "number", "boolean", "array", "object", "function", "undefined", "int", "float", "null", "NaN", "Infinity"

• optional deve ser um booleano, se não definir ele, vem por padrão false, e se definido como true aquele campo pode ficar vazio.

• valueDefault essa propriedade, se definida, preenche o campo com um valor padrão caso aquele campo esteja vazio na hora de cadastrar. É possível usar uma forma de valor padrão nativo, utilizando as constantes staticas da classe Localdb: AUTO_INCREMENT: ele preenche auto incrementando começando do 0. MATH_RANDOM: ele preenche com um valor aleatório de 0 à 1. UUID: ele preenche com um uuid. DATE_NOW: ele preenche com a data atual, ano/mes/dia. HOURS_NOW: ele preenche com a hora atual. YEAR_NOW: ele preenche com o ano atual. DAY_NOW: ele preenche com o dia atual. TIME_STAMP: ele preenche com o método Date.now(). Além disso é possível atribuir uma função para gerar um valor padrão personalizado, ganhando como paramêtro da função os proprios dados daquela entidade.

• uniqueIndex uma propriedade booleana que vem como padrão false, se for true, aquele campo não permitirá duplicação de valores.

2. O sync-localdb armazena os dados localmente, e cria as tables em tempo de execução, ou seja, se vc rodar o código uma vez criando a tabela "users", e depois mudar o nome para "usuarios", ele criara uma outra tabela diferente, ficando uma tabela "users" e outra tabela "usuarios". Para não ficar acumulando tabelas que nao será mais utilizadas, utilizamos uma função monitora, que depois de um certo tempo de execução (por padrão 3 minutos), ele delete todas as tabelas em desuso no código, se quiser mudar esse tempo, é possível declarando o novo tempo no construtor da classe localdb, sendo o mínimo permitido, 0.25 minutos.

const localdb = new Localdb(1); // A cada 1 minuto de tempo de execução do código, ele apagara as tabelas em desuso
// voce ainda tem a opção de passar um segundo parâmetro que seria o `disableMonitor` que por padrão é 'false', se quiser desativar o monitoramento defina como true

userTable.renameTable("users", "usuarios"); // alterou o nome da tabela 'users' para 'usuarios'
userTable.renameField("id", "userID"); // alterou o campo 'id' da tabela contida na instancia 'userTable', renomeando para 'userID'
userTable.dropField("age"); // deletou a coluna 'age' e todos os dados contida nela da tabela contida na instancia 'userTable'

CREATE

• save: ele espera um objeto representando a entidade defina por você na criação da tabela, ele salva como uma linha da tabela retornando false ou true dependendo se salvou com sucesso ou não.

READ

• searchAll: retorna todas as linhas da tabela em um array com as entidades contendo todos os campos.

• searchAtRow: retorna a entidade de acordo com o número da linha passado no parâmetro. Obs: se passar -1 como parâmetro, retornará a ultima linha adicionada.

• searchFieldsAtRow: ao inves de retornar toda a entidade, traz apenas os campos requeridos que podem ser passados com uma string com o nome do campo, ou um array com o nome dos campos. Ele retorna apenas os campos contido na linha passada no parâmetro 'row'. Se nao achar, retorna null.

• searchFieldsByCustom: assim como 'searchFieldsAtRow' retorna apenas os campos passados, porém ao invés de passar o número da linha, deve passar um callback com a condição para filtrar os dados. Se nao achar, retorna null.

• findByCustom: encontra a linha da tabela em que a função de filtro customizada, retorne true, a função 'condiction' é como se fosse um callback do método 'filter' e 'find' dos arrays. Se nao achar, retorna null.

• findAllByCustom: encontra um array contendo todos as linhas em que o callback 'condiction' retorna true. Se nao achar, retorna null.

UPDATE

• updateAtRow: atualiza a linha da tabela corresponde ao parâmetro 'row', com a entidade que deseja alterar. retorna false ou true dependendo se alterou com sucesso ou não.

• updateFieldsAtRow: ao inves de substituir uma entidade inteira pela a nota entidade, em um objeto tendo 'field' com o nome do campo e 'value' tendo o novo valor que deseja atribuir aquele campo, ou um array de objetos contendo o campo e seu valor que sera alterado. atualiza a linha da tabela corresponde ao parâmetro 'row'. retorna false ou true dependendo se alterou com sucesso ou não.

• updateByCustom: atualiza a primeira linha da tabela em que a função de filtro customizada, retorne true, é necessário passar a entidade com os campos atualizados. retorna false ou true dependendo se alterou com sucesso ou não.

• updateFieldsByCustom: ao invés de atualizar a linha inteira da tabela que foi filtrada através do callback passado no paramêtro 'condiction', ele altera apenas os campos passados. retorna false ou true dependendo se alterou com sucesso ou não.

DELETE

• deleteAtRow: deleta a linha passada pelo o parâmetro 'row' da tabela. retorna false ou true dependendo se deletou com sucesso ou não.

• deleteByCustom: deleta a linha da tabela em que a função do filtro customizada seja verdadeira. retorna false ou true dependendo se deletou com sucesso ou não.

OUTROS

• existValueInTable: retorna true caso exista aquele valor passado no paramêtro 'value' existe no campo passado no paramêtro 'field', se nao retorna false

• existAtRow: retorna true caso exista essa linha na tabela.

O que mudou na versão v2.0?

• Criar tabelas: A forma de criar tabelas mudou um pouco da versão 1.0, além de passar a nome da tabela e os campos com suas regras, nesse objeto deve conter também a propriedade 'migration' passando uma string com um nome de migration que deseja.

const userTable = localdb.createTable({
    tableName: "users",
    fields: [
        {
            fieldName: "userID",
            fieldType: "string",
            uniqueIndex: true,
            valueDefault: Localdb.value_default.AUTO_INCREMENT
        },
        {
            fieldName: "name",
            fieldType: "string"
        },
        {
            fieldName: "age",
            fieldType: "integer"
        }
    ], // Além de passar essas propriedades, não esqueça de passar a migration
    migration: "create_table",
    // restart: false,
    // index: 0
});

Agora ele criará a tabela na primeira execução, e nas próximas execuções ele irá pegar do cache da migration, e não lerá novamente as informações da função 'createTable'.

• Renomear tabelas: Agora para usar o 'table.renameTable' é necessário também passar um objeto contendo a migration. Exemplo:

userTable.renameTable("user", {migration: "rename_table"});

No caso do exemplo acima, alterou o nome da tabela de "users" (o nome atual) para "user". Porém internamente essa tabela ainda é referenciada como "user" no cache da migration, pois se não o usuário iria ter que mudar a propriedade 'tableName' toda vez que usasse um 'renameTable'. O mais interessante do uso da migration nessa função é que você não precisa se preocupar em remover o código para não haver duplicações, eu posso deixar o renameTable em todas as execuções que a lib entenderá que já foi executada e assim não executará novamente, o que na versão 1.0 não era possível.

• Renomear campos: Para utilizar o 'table.renameField' também é necessário passar um objeto contendo a migration.Exemplo:

userTable.renameField("name", "completeName", {migration: "rename_field"});

Neste exemplo ele está alterando o nome do campo "name" para "completeName" da tabela instânciada no 'userTable', que nesse caso é a tabela "user". Assim como no 'renameTable', o sync-localdb identificará se ja foi ou não executada através da migration. Uma observação a se fazer, é que se você utilizar o renameField e depois for dar um 'restart' na tabela, você deve deixar os campos da propriedade 'fields' correto com o nome renomeado. Uma sugestão, é não utilizar o 'restart' na tabela para renomear um campo se já tiver dados cadastrados com o nome do campo antigo, pois o 'restart' só reescreverá as regras dos campos no cache, enquanto o renameField irá alterar o nome do campo no cache da migration e ao mesmo tempo alterar o nome do campo antigo para o novo, nas linhas de dados já adicionados na tabela. Porém se não houver nenhum dado adicionado ainda, é melhor e mais prático apenas restartar a tabela com a correção no nome do campo.

• Dropar campos: Para utilizar o 'table.dropField' assim como o 'renameTable' e 'renameField', é necessário passar um objeto contendo a migration. Veja o exemplo:

userTable.dropField("age", {migration: "drop_field"});

Aqui, estamos deletando da tabela instânciada no 'userTable', que nesse caso é a tabela "user", o campo "age", o sync-localdb identificará se ja foi ou não executada através da migration. Uma sugestão, que foi dado no 'renameField' mas que também serve para o 'dropField', é que o ideal apenas utilizar o 'restart' para remover campos da tabela no caso de não houver dados adicionados com a estrutura da tabela anterior, pois quando restarta a tabela ele apenas reescreve as regras dos campos no cache das migrations, enquanto o 'dropField' ira remover o campo do cache das migrations e remover tambem de cada linha adicionada nessa tabela.

const localdb = new Localdb(1); // O valor passado será multiplicado por 60, ou seja esse 1 é equivalente a 60s ou a 1m.
localdb.clearMigrations();

No exemplo acima, as migrations que não foram utilizadas nessa executação, serão deletados do cache em 1 minutos após rodar o código.