_comuns/README.md

p-comuns — Pacote Compartilhado e-licencie

Pacote de tipos, utilitários e configurações compartilhadas entre todos os subprojetos da plataforma e-licencie (back-end Node.js, front-end Vue 3 / TSX).

---

✅ Configuração do BiomeJS nos Subprojetos

Este guia mostra como usar a configuração base do Biome disponível neste pacote (Documentos/biome.json). Todos os subprojetos herdam essas regras via extends.

1. Adicionar o p-comuns como dependência

pnpm add --save-dev p-comuns
# ou atualizar se já existir:
pnpm up p-comuns

---

2. Instalar o Biome

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

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

---

3. Criar biome.json na raiz do subprojeto

{
  "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["node_modules/p-comuns/Documentos/biome.json"],
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "includes": ["**/*.{ts,tsx,vue}"]
  }
}

vcs.useIgnoreFile: true faz o Biome respeitar o .gitignore automaticamente — arquivos como dist/, node_modules/ etc. são ignorados sem configuração adicional.

---

4. Adicionar scripts no package.json

{
  "scripts": {
    "biome": "pnpm exec biome check --write",
    "check": "pnpm run biome && npx tsc --noEmit"
  }
}

---

5. Configurar o VS Code (.vscode/settings.json)

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "always",
    "source.fixAll.biome": "always"
  },
  "[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[javascriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[vue]": { "editor.defaultFormatter": "biomejs.biome" },
  "[css]": { "editor.defaultFormatter": "biomejs.biome" },
  "[json]": { "editor.defaultFormatter": "biomejs.biome" },
  "[jsonc]": { "editor.defaultFormatter": "biomejs.biome" },
  "editor.rulers": [100],
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}

💡 Biome formata Vue .vue nativamente desde a v2.3 — não precisa do Prettier ou Vetur para formatação!

---

🔑 Regras da configuração base (Documentos/biome.json)

O que está ativado:

Categoria	Regras notáveis
Correctness	noUnusedVariables, noUnusedImports, noVueSetupPropsReactivityLoss
Vue 3 específico	noVueVIfWithVFor, useVueVForKey, noVueDuplicateKeys, noVueReservedKeys
Style	useAsConstAssertion, useSelfClosingElements, useConsistentArrayType (shorthand T[])
Nursery Vue	noVueArrowFuncInWatch, useVueDefineMacrosOrder, useVueConsistentVBindStyle
Security	noDangerouslySetInnerHtml (warn)

Globals do Vue (sem necessidade de importar):

defineProps, defineEmits, defineExpose, withDefaults, defineModel, defineOptions, defineSlots

Formatação:

• Indentação: 2 espaços
• Linha máxima: 100 caracteres
• Aspas: duplas
• Ponto-e-vírgula: apenas quando necessário
• Trailing comma: sempre
• Line ending: LF (\n)

---

✅ 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

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 Completo

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

Operadores Suportados (operadores26)

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

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

import { zFiltro26 } from "p-comuns"

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

---

📚 Veja também

• AGENTS.md — Guia para assistentes de IA (padrões, convenções, arquitetura)
• Biome 2.x Docs
• Vue 3 Composition API