@praxisui/specification

@praxisui/specification

🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

• Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
• O Quickstart demonstra a integração das bibliotecas @praxisui/* em um app Angular, incluindo instalação, configuração e uso em telas reais.

Biblioteca TypeScript para criar validações composáveis (Specification Pattern), com DSL legível, serialização JSON, metadados ricos e registries de funções/transformações.

Visão Geral

@praxisui/specification provê fábricas e composições para você declarar regras de validação de forma segura e expressiva:

• Composições booleanas: and, or, not, xor, implies.
• Comparações e validações de campos (ex.: greaterThan, contains, minLength).
• Validadores condicionais (ex.: requiredIf).
• DSL legível e serialização/descrição JSON para persistência.
• Metadados para mensagens, códigos e configurações de UI.

Este pacote é compatível com Angular apps (peer deps Angular), mas pode ser usado em qualquer projeto TypeScript/Node.

Instalação

npm i @praxisui/specification @praxisui/specification-core

Peer dependencies (Angular v20):

• @angular/core ^20.0.0
• @angular/common ^20.0.0

Dependências em runtime:

• @praxisui/specification-core (instale junto)
• tslib (já vem por padrão em projetos Angular/TS modernos)

Exemplo Rápido

import { SpecificationFactory } from '@praxisui/specification';

// Regra: idade > 18, email contém '@' e telefone obrigatório se role == 'admin'
const userSpec = SpecificationFactory.and(
  SpecificationFactory.greaterThan('age', 18),
  SpecificationFactory.contains('email', '@'),
  SpecificationFactory.requiredIf(
    'phone',
    SpecificationFactory.equals('role', 'admin')
  )
);

// Validação
const user = { age: 25, email: '[e-mail]', role: 'admin' };
const ok = userSpec.isSatisfiedBy(user); // false (faltou phone)

// DSL legível
console.log(userSpec.toDSL());
// Ex.: age > 18 && contains(email, "@") && requiredIf(phone, role == "admin")

// JSON (persistência/transporte)
const json = userSpec.toJSON();

Dicas de Uso

• Para regras personalizadas, registre funções: FunctionRegistry.getInstance().register('isValidCPF', fn).
• Para transformar valores antes da comparação (ex.: upper/trim), use TransformRegistry.
• Para compor validações complexas por formulário/coleção, veja utilitários em SpecificationFactory.

Documentação

• Guia detalhado e exemplos: projects/praxis-specification/docs/README.md
• Conceitos (Rules Engines & Specifications): docs/concepts/rules-engines-and-specifications.md

Build local e Publicação

# build do pacote
ng build praxis-specification

# gerar tarball para inspeção (dentro do dist)
cd dist/praxis-specification && npm pack

# publicar (exige configuração de token/registry)
npm publish --access public

O pacote publicado inclui este README.md via configuração de assets no ng-package.json.

Links

• Repositório: https://github.com/codexrodrigues/praxis
• Issues: https://github.com/codexrodrigues/praxis/issues