_comuns/README.md

✅ Uso do BiomeJS para Autoformatação

Este guia mostra como configurar o BiomeJS para formatar e analisar código JavaScript/TypeScript no seu projeto.

---

1. Incluir o pacote de configuração comum

Certifique-se de que o pacote p-comuns (ou outro com a configuração compartilhada) esteja disponível no seu projeto. Ele deve conter o arquivo Documentos/biome.json.

pnpm up p-comuns

---

2. Instalar o Biome com pnpm

pnpm add --save-dev --save-exact @biomejs/biome@2.1.4

🎯 Use --save-exact para garantir consistência de versões entre ambientes.

---

3. Criar o arquivo de configuração na raiz do projeto

Crie um arquivo chamado biome.json com o seguinte conteúdo:

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["./node_modules/p-comuns/Documentos/biome.json"],
  "files": {
    "includes": ["src/**/*.{js,ts,jsx,tsx}"]
  }
}

⚠️ Verifique o caminho correto do extends relativo à raiz do seu projeto. Use ./ sempre que possível para evitar erros de resolução.

---

4. Adicionar script no package.json

Inclua o comando abaixo em "scripts":

{
  "scripts": {
    "biome": "pnpm exec biome check --write",
  }
}

Isso permite executar:

pnpm biome

O comando irá formatar e aplicar as regras de lint nos arquivos do diretório src/.

---

✅ Dica extra: formatar todos os arquivos

Se quiser aplicar o Biome a todo o projeto (não só src/), altere o include:

"includes": ["**/*.{js,ts,jsx,tsx}"]

adicionar em .vscode/settings.json

{ "editor.defaultFormatter": "biomejs.biome", "[javascript]": { "editor.defaultFormatter": "biomejs.biome" }, "[javascriptreact]": { "editor.defaultFormatter": "biomejs.biome" }, "[typescript]": { "editor.defaultFormatter": "biomejs.biome" }, "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" }, "[json]": { "editor.defaultFormatter": "biomejs.biome" }, "[jsonc]": { "editor.defaultFormatter": "biomejs.biome" }, "[vue]": {"editor.defaultFormatter": "octref.vetur"}, "editor.codeActionsOnSave": { "source.organizeImports.biome": "always", "source.fixAll.biome": "always" } }

---

✅ Sistema de Filtros (tipoFiltro26)

O sistema tipoFiltro26 foi projetado para gerar automaticamente a tipagem de filtros compatíveis com operadores padrão do PostgreSQL, a partir de um tipo base T.

Principais características:

• Tipagem forte e segura (Typescript)
• Suporte a aninhamento de objetos
• Operadores lógicos E (AND) e OU (OR)
• Validação de operadores permitidos por tipo de dado (string, number, boolean)

Estrutura do Filtro

O filtro segue uma estrutura onde chaves representam campos (simples ou aninhados) e valores representam condições com operadores específicos.

1. Campos Simples

{
  idade: { ">=": 18 }
}

2. Campos Aninhados

{
  carro: {
    ano: { "=": 2020 }
  }
}

3. Operadores Lógicos

Operador E (AND): Todos devem ser verdadeiros.

{
  E: [
    { idade: { ">=": 18 } },
    { nome: { like: "%pa%" } }
  ]
}

Operador OU (OR): Pelo menos um deve ser verdadeiro.

{
  OU: [
    { idade: { "<": 18 } },
    { idade: { ">=": 60 } }
  ]
}

4. Exemplo Complexo Complet

{
  idade: { ">=": 18 },
  OU: [
    { nome: { like: "%pa%" } },
    {
      E: [
        { carro: { ano: { "=": 2020 } } },
        { carro: { modelo: { in: ["Civic"] } } }
      ]
    }
  ]
}

Operadores Suportados (operadores26)

Os operadores são fornecidos pelo enum operadores26 e são restritos pelo tipo do campo:

• Number: =, !=, >, >=, <, <=, in
• String: =, !=, like, in
• Boolean: =, !=, in

Nota: Atualmente não há suporte automático para null, date, jsonb ou arrays como tipos de campo raiz (exceto arrays dentro do operador in).

Validação em Tempo de Execução (Zod)

O sistema inclui um validador Zod zFiltro26 para validação estrutural dos objetos de filtro recebidos (ex: via API).

import { zFiltro26 } from './tipoFiltro.26';

// Valida a estrutura (não checa existência de colunas no DB)
zFiltro26.parse(objetoFiltro);