Repositório central de tipos, DTOs, enums e interfaces compartilhadas para os projetos da ANPD.
⚠️ VERSÃO BETA - Esta biblioteca está em desenvolvimento ativo. Use com cautela em produção.
Este pacote centraliza todos os tipos TypeScript reutilizáveis, Data Transfer Objects (DTOs), enums e interfaces utilizados nos diversos serviços e aplicações da ANPD. O objetivo é garantir padronização, reuso de código e consistência tipada em toda a stack, servindo como a fonte única da verdade para os contratos de dados.
📦 Publicado no NPM: @anpdgovbr/shared-types
# Com npm (fixando a versão beta)
npm install @anpdgovbr/shared-types@0.2.0-beta-0
# Com yarn
yarn add @anpdgovbr/shared-types@0.2.0-beta-0
# Com pnpm
pnpm add @anpdgovbr/shared-types@0.2.0-beta-0Esta biblioteca suporta tanto CommonJS quanto ES Modules, permitindo uso flexível em diferentes ambientes:
// Import padrão (funciona em ambos os módulos)
import { UserDto, AcaoAuditoria } from "@anpdgovbr/shared-types"
// Import específico de tipos
import type {
BaseQueryParams,
BasePaginatedResponse,
} from "@anpdgovbr/shared-types"
// Import de utilitários (funções runtime)
import { isStatusInterno, coerceStatusInterno } from "@anpdgovbr/shared-types"Importe os tipos diretamente do pacote. O ponto de entrada principal exporta todas as entidades "core" do sistema.
import {
UserDto,
AcaoAuditoria,
BaseQueryParams,
BasePaginatedResponse
} from "@anpdgovbr/shared-types"
// Exemplo de uso em paginação
const params: BaseQueryParams = {
page: 1,
pageSize: 10,
search: "termo de busca",
orderBy: "nome",
ascending: true
}
// Exemplo de resposta tipada
const response: BasePaginatedResponse<UserDto> = {
data: [...],
total: 50
}import { UserDto, AuditLogDto, AcaoAuditoria } from "@anpdgovbr/shared-types"
// Definindo um usuário
const usuario: UserDto = {
id: "uuid-123",
email: "joao@anpd.gov.br",
nome: "João Silva",
perfilId: 1,
active: true,
}
// Log de auditoria
const auditLog: AuditLogDto = {
id: 1,
tabela: "usuarios",
acao: AcaoAuditoria.CREATE,
registroId: 123,
userId: usuario.id,
email: usuario.email,
// Metadados de contexto (herdados de AuditContext)
ip: "203.0.113.10",
userAgent: "Mozilla/5.0",
contexto: "Cadastro inicial",
// Identificadores de correlação / trace distribuído (opcionais)
requestId: "req-01HQZ0X9W5K7M6N7JZ8R4XYTQ2",
traceId: "0af7651916cd43dd8448eb211c80319c",
spanId: "b7ad6b7169203331",
criadoEm: new Date(),
}import {
PermissaoDto,
PermissaoPayload,
AcaoPermissao,
RecursoPermissao,
} from "@anpdgovbr/shared-types"
// Criando uma permissão
const novaPermissao: PermissaoPayload = {
perfilId: 1,
acao: "Editar" as AcaoPermissao,
recurso: "Processo" as RecursoPermissao,
permitido: true,
}
// Resultado da criação
const permissaoCriada: PermissaoDto = {
id: 10,
acao: "Editar",
recurso: "Processo",
permitido: true,
perfilId: 1,
}import type {
Cargo,
AllowedField,
ALLOWED_FIELDS,
} from "@anpdgovbr/shared-types"
// Exemplo de uso dos tipos em posições de tipo
type CargoResumo = Pick<Cargo, "id" | "titulo_canonico" | "familia">
// Campos AD permitidos (array somente leitura)
const campos: ReadonlyArray<AllowedField> = ALLOWED_FIELDSimport type {
GraphUser,
GraphGroup,
GraphPagedResponse,
} from "@anpdgovbr/shared-types"
async function listarUsuarios(): Promise<GraphPagedResponse<GraphUser>> {
// ... sua chamada ao Graph aqui
return { value: [], "@odata.nextLink": undefined }
}src/
├── base/ # 🏗️ Interfaces base e contratos fundamentais
│ ├── base-entity.interface.ts # Entidade base com ID
│ ├── named-entity.interface.ts # Entidade nomeada
│ ├── soft-delete.interface.ts # Exclusão lógica
│ ├── audit-context.interface.ts # Contexto de auditoria
│ └── audited-entity.interface.ts # Entidade auditável
│
├── dto/ # 📄 Data Transfer Objects
│ ├── user.dto.ts # Usuário do sistema
│ ├── processo.dto.ts # Processos (Input/Output/Importação)
│ ├── controlador.dto.ts # Controladores de dados
│ ├── permissao.dto.ts # Sistema de permissões
│ └── ... # Outros DTOs
│
├── enums/ # 🔢 Enumerações e tipos constantes
│ ├── acao-auditoria.enum.ts # Ações de auditoria
│ ├── permissao.enum.ts # Tipos de permissão
│ ├── status-interno.enum.ts # Status internos
│ └── ... # Outros enums
│
├── interfaces/ # 🔌 Interfaces utilitárias
│ ├── base-query-params.interface.ts # Parâmetros de consulta
│ ├── base-paginated-response.interface.ts # Resposta paginada
│ └── enum-data.interface.ts # Dados enumerados
│
├── domain/ # 🧭 Tipos de domínios específicos (ex.: RH)
│ └── rh/ # Cargos, Estrutura Organizacional, Vocabulários RH
│
└── index.ts # 📥 Ponto de entrada principal
# Compilar o projeto (CommonJS + ESM)
npm run build
# Modo watch para desenvolvimento
npm run watch
# Limpar arquivos de build
npm run clean
# Verificar lint
npm run lint
# Corrigir problemas de lint automaticamente
npm run lint:fix
# Formatar código
npm run format
# Verificar formatação
npm run format:check
# Verificar tipos sem gerar arquivos
npm run type-check
# Gerar documentação com Typedoc
npm run docs
# Servir documentação localmente
npm run docs:serveA documentação completa da API é gerada automaticamente usando Typedoc a partir dos comentários TSDoc no código fonte.
# Gerar documentação HTML em ./docs
npm run docs
# Servir documentação localmente para visualização interativa
npm run docs:serveApós executar npm run docs, abra o arquivo ./docs/index.html no navegador para navegar pela documentação interativa dos tipos, interfaces, enums e DTOs disponíveis.
-
Tipos Core (Transversais)
- Adicione em
src/na pasta apropriada (dto/,enums/,interfaces/,base/) - Exporte no
index.tsda pasta - Documente usando TSDoc
- Adicione em
-
Exemplo de novo DTO:
// src/dto/novo-tipo.dto.ts
import { BaseEntity } from "../base"
/**
* Representa um novo tipo no sistema.
*
* @remarks
* Descrição detalhada do propósito e uso do tipo.
*
* @example
* ```typescript
* const exemplo: NovoTipoDto = {
* id: 1,
* nome: "Exemplo"
* }
* ```
*/
export interface NovoTipoDto extends BaseEntity {
nome: string
// outras propriedades...
}- Adicione no barrel export:
// src/dto/index.ts
export { NovoTipoDto } from "./novo-tipo.dto"Esta biblioteca está atualmente em versão beta (0.1.7-beta-x). Isso significa:
- ✅ Funcional: Os tipos estão funcionais e podem ser usados
⚠️ Em desenvolvimento: Pode haver mudanças que quebrem compatibilidade- 🧪 Testando: Estamos refinando a API e estrutura
- 🤝 Feedback bem-vindo: Sugestões e issues são muito apreciados
- Desenvolvimento: Fique à vontade para usar e testar
- Produção: Use com cautela e fixe a versão específica
- Atualizações: Acompanhe o CHANGELOG para mudanças importantes
- 📝 Documentação: Todos os novos tipos devem ser documentados utilizando o padrão TSDoc.
- 🎯 Novos Tipos:
- Se o tipo for transversal e aplicável a múltiplos domínios, adicione-o em
src/. - Se o tipo for específico de um contexto de negócio, crie ou utilize a pasta do domínio correspondente (futura implementação).
- Se o tipo for transversal e aplicável a múltiplos domínios, adicione-o em
- 🔧 Consistência: Mantenha a padronização de nomenclatura e estrutura de arquivos.
Este projeto segue o Semantic Versioning:
- MAJOR: Mudanças que quebram compatibilidade
- MINOR: Novas funcionalidades mantendo compatibilidade
- PATCH: Correções de bugs mantendo compatibilidade
- BETA: Versões de desenvolvimento (ex: 0.1.7-beta)
Para publicar uma nova versão beta:
# 1. Atualizar versão no package.json para X.Y.Z-beta
npm version prerelease --preid=beta
# 2. O script prepublishOnly irá rodar automaticamente:
# - build, lint e format:check
# 3. Publicar no NPM com tag beta
npm publish --tag betaPara publicar versão estável:
# 1. Atualizar versão no package.json (remover -beta)
npm version patch|minor|major
# 2. Publicar no NPM
npm publish- Issues: GitHub Issues
- Documentação: Este README e comentários TSDoc no código
- Equipe: DDSS/CGTI/ANPD
💻 Projeto mantido pela equipe DDSS/CGTI/ANPD.
📄 Licença: MIT