bun-sqlight

bun-sqlight é uma camada de abstração SQLite leve, com zero dependências e foco em segurança de tipos, construída especificamente para o runtime Bun. Ela possui um construtor de consultas fluente, controle de histórico do banco de dados (migrações e rollbacks) e segurança de tipos automática com configuração zero diretamente no editor.

Funcionalidades Principais

• Segurança de Tipos com Configuração Zero: Escreva suas migrações ou crie tabelas e sua IDE ganhará autocomplete instantâneo dos nomes de tabelas e colunas. Não é necessário importar schemas de tipo complexos ou declarar parâmetros genéricos (<TableMap>).
• Motor de Migrações Versionadas: Acompanhe o histórico do banco de dados através de arquivos simples de migração com funções up/down.
• Alteração de Schemas: Suporte para adicionar, remover e renomear colunas com atualização em tempo real no TypeScript.
• Query Builder Fluente: Construa e encadeie selects, joins, inserts, updates e deletes integrados diretamente ao Bun:sqlite.
• Segurança e Proteção de Queries: Validação nativa que bloqueia injeções de SQL, impede queries destrutivas sem filtros (como UPDATE/DELETE sem WHERE) e gera UUIDs e timestamps atualizados automaticamente.

Instalação

bun add bun-sqlight

Início Rápido

1. Configurar a Biblioteca

Crie um arquivo sqlight.config.json na raiz do seu projeto:

{
  "db": "production.db",
  "migrationsDir": "./migrations"
}

2. Escrever uma Migração

Crie um arquivo dentro do diretório ./migrations/ (ex: ./migrations/0001_create_users.ts):

import { Sqlight, SchemaBuilder } from 'bun-sqlight';

export function up(db: Sqlight) {
  db.createTable('users', (table: SchemaBuilder) => {
    table.id();
    table.string('name');
    table.string('email', { unique: true });
  });
}

export function down(db: Sqlight) {
  db.dropTable('users');
}

3. Executar os Comandos da CLI

Crie novos templates e rode as migrações para aplicar no banco de dados e atualizar as tipagens automaticamente:

# Criar um novo template de migração
bunx bun-sqlight create criar_usuarios

# Rodar migrações pendentes
bunx bun-sqlight migrate

# Reverter a última migração aplicada
bunx bun-sqlight rollback

# Checar o status do histórico de migrações
bunx bun-sqlight status

4. Consultar o Banco (Com Autocomplete!)

Instancie o banco e consulte a tabela criada. O autocomplete para 'users', 'name' e 'email' funcionará de forma totalmente transparente e automática!

import { Sqlight } from 'bun-sqlight';

const db = new Sqlight('production.db');

// Autocomplete e validação de tipos automática em from() e select()
const users = db.from('users').select('name', 'email').run();
console.log(users);

5. Recursos Avançados da API

• Transações: Execute várias queries agrupadas com commit e rollback (síncronos/assíncronos) automáticos em falhas:

  await db.transaction(async (trx) => {
    await trx.insert('users', { name: 'Alice' }).run();
  });

• Comparadores Avançados: Filtros limpos como startsWith, contains, in, between:

  db.from('users').where('name', 'startsWith', 'Ali').run();

• Agrupamento de Relações (asKey): Agrupe automaticamente as linhas do join em um objeto aninhado:

  db.select('*').from('users').join('orders.user_id', 'users.id', { asKey: 'orders' }).run();

• Inspeção de Queries: Exiba o comando SQL gerado sem executá-lo usando o método .toSQL().
• Sobrescrita de Validação: Execute qualquer SQL ou ignore limites usando a opção { force: true } nos métodos .run() e .raw().

Documentação

Para a documentação completa da API, recursos do construtor de consultas e detalhes de schemas, veja docs.md (em inglês) ou docs.pt-BR.md (em português).